Evergage(Swizzling) Category Reference

“Swizzling” is a technique that Marketing Cloud Personalization can use to automatically listen for info it needs to support Personalization features you’ve enabled. Swizzling eliminates the need for you to manually forward info to Personalization via API calls.

• Open URL for Testing

  • See handleOpenURL: for details. Your app must still declare one of the iOS open-URL delegate methods to allow Personalization to ‘listen’ as well.
  • This swizzling can be disabled, see swizzlingEnabled.

• Push Notifications

  • APNS token
    • For more information, see setAPNSToken:. Your app must still declare the delegate method to allow Personalization to “listen” as well.
  • Firebase token
    • For more information, see setFirebaseToken:. Your app must still declare the delegate method to allow Personalization to “listen” as well.
  • Notification received
    • For more information, see handleNotification:actionIdentifier:. Your app must still declare one of the iOS notification-received methods to allow Personalization to “listen” as well.
  • This swizzling can be disabled, see swizzlingEnabled.

• UIViewController

  • viewDidAppear: and viewWillDisappear:. To manage the lifecycle of the associated [UIViewController(Evergage) evergageScreen], stopping view time tracking and releasing resources as appropriate.

  • This swizzling currently cannot be disabled.

    iOS unfortunately does not enforce classes to call [super viewDidAppear:] and [super viewWillDisappear:], despite documentation stating “you must call super at some point in your implementation”. Be sure your classes comply.

    Important

Personalization takes care to swizzle safely:

• Personalization will only extend found methods - If your app isn’t declaring some method to discover information, Personalization won’t add a listener for you. While this approach may require slightly more app code, it makes clear what Personalization can listen to, and avoids potential issues where adding a new method could change behavior (for example, adding a higher-priority callback resulting in some other callback not getting called at all).
• Swizzle exactly once, using dispatch_once
• For static classes, swizzle in a category’s +load method
• For dynamic delegate classes discovered at runtime:
  • If the delegate already exists, Personalization dispatch_once swizzles the delegate class
  • Otherwise, Personalization dispatch_once swizzles setDelegate:. When Personalization sees the first non-nil delegate, it dispatch_once swizzles the delegate class
  • Personalization only ever swizzles the first non-nil delegate. This measure We noticed some other 3rd party libraries replacing a delegate with a proxy to the original delegate, and swizzling both classes led to double-processing.

Below you can see a simplified version of how Personalization swizzles a method. Personalization also takes precautions to try or catch NSExceptions, etc.

1@implementation SomeClass (Evergage)
2+ (void)load {
3    static dispatch_once_t onceToken;
4    dispatch_once(&onceToken, ^{
5        __block IMP originalIMP = [EVGSwizzler replaceMethod:@selector(someMethod:) inClass:[self class] withBlock:^(id _self, id someParam) {
6            // Call original implementation:
7            ((void(*)(id,SEL,id))originalIMP)(_self, @selector(someMethod:), someParam);
8
9            // ... Personalization processing ...
10        }];
11    });
12}
13@end
14
15@implementation EVGSwizzler
16+ (nullable IMP)replaceMethod:(nonnull SEL)selector inClass:(nonnull Class)cls withBlock:(nonnull id)block {
17    // Finds method on this class or superclass
18    Method originalMethod = class_getInstanceMethod(cls, selector);
19    if (!originalMethod) {
20        // No orignal method found, abort
21        return nil;
22    }
23
24    IMP originalIMP = method_getImplementation(originalMethod);
25    if (!originalIMP) {
26        // No original implementation found, abort
27        return nil;
28    }
29
30    // Replaces the implementation with the block, which calls the returned original implementation
31    IMP newIMP = imp_implementationWithBlock(block);
32    class_replaceMethod(cls, selector, newIMP, method_getTypeEncoding(originalMethod));
33    return originalIMP;
34}
35@end

If swizzling is enabled for the Personalization iOS SDK.

1+ (BOOL)swizzlingEnabled

Availability

1.3.0

Discussion

Defaults to YES (enabled). To disable, add EvergageSwizzlingEnabled to the app’s Info.plist file with a boolean value of NO. See Evergage(Swizzling) for more details, including additional code you must write to forward information to Personalization.

You do not normally need to call this method, but simply ensure your UIApplicationDelegate defines an open-URL method, and add your app’s Personalization URL scheme.

1- (BOOL)handleOpenURL:(nonnull NSURL *)url

Parameters

Return Value

YES, if the URL was Personalization specific

Availability

1.2.0 (moved from Evergage.h)

Discussion

By default, Personalization will swizzle any of these open-URL methods you define:

• application:openURL:options:
• application:openURL:sourceApplication:annotation:
• application:handleOpenURL:

However, if you disable swizzling in the Info.plist (see swizzlingEnabled), then you will need to manually call this method from your open-URL method.

This method enables Personalization to handle Personalization-related URLs. Used so test campaigns can easily and codelessly be managed by opening URLs in Safari on the device.

Your app must also add support for this Personalization URL scheme. For more information, see the Testing Guide.

For the URL formats below:

• <URLScheme> is the Personalization-generated URL scheme for the app, which is located in the Personalization UI. To retrieve the URL scheme, select Dataset, then Settings > Sources > Apps > (this app) > URL Scheme: (format “evgxxxxx”).
• <ExpID> is the ID of a specific campaign experience, which can be found in the Personalization UI. To retrieve the ExpID, select the Dataset, then Campaigns > Campaign Summary of the campaign the experience is in.
• These URLs do not aggregate or combine. The most recent one determines the behavior.
• Testing lasts for 30 minutes, or until the app is terminated or another test URL is entered.

There are three test URL formats:

• Test All Campaigns:

  1<URLScheme>://test/all

  In addition to default behavior of showing mobile campaigns in the Published state, also show mobile campaigns that are in the Test state. All campaign rules will still be active.

• Test a Specific Experience:

  1<URLScheme>://test/<ExpId>

  In addition to default behavior of showing mobile campaigns in the Published state, also show the particular experience of a mobile campaign, regardless of that campaign’s state and rules that normally determine when its shown.

• Stop Testing:

  1<URLScheme>://test/none

  Return to the default behavior of showing mobile campaigns in the Published state only.

See Also

• Testing Guide

Typically, you don’t need to directly invoke this method. If your app uses Apple Push Notification Service (APNS), simply ensure the following:

• Confirm that your app’s UIApplicationDelegate defines the method application:didRegisterForRemoteNotificationsWithDeviceToken:.
• Your app calls registerForRemoteNotifications on UIApplication regularly on/after launch, as applicable (such as after the user has completed the notification onboarding process and opted in). Doing so ensures periodic calls to the mentioned delegate method, thereby providing the ability to react off of permission changes, etc.
• For iOS versions 10 and above, use the UNUserNotificationCenter to request user permission for displaying notifications.

1- (void)setAPNSToken:(nonnull NSData *)token

Parameters

Availability

1.3.0

Discussion

By default, Personalization will swizzle the method application:didRegisterForRemoteNotificationsWithDeviceToken:, if defined. However, if you disable swizzling in the Info.plist, you will need to call this method directly to provide the APNS token.

This method notifies Personalization when the app’s APNS token changes, in order to support Personalization push notification campaigns.

This method will have no effect if you don’t enable support for push notifications. For more information, see [EVGClientConfigurationBuilder usePushNotifications].

Personalization will only send push notifications to the most recent user. For more information, see [Evergage userId].

Personalization automatically tracks clicks and opens for typical push notifications. However, when you need to call a method to track a click, use [EVGContext trackClickthrough:actionIdentifier:].

The setAPNSToken: method can automatically determine if the token is for APNS production vs APNS sandbox.

For more information, see Push Notifications.

See Also

• [EVGClientConfigurationBuilder usePushNotifications]
• [Evergage userId]
• [EVGContext trackClickthrough:actionIdentifier:]
• setFirebaseToken:

The setFirebaseToken: method notifies Personalization when your app’s Firebase Messaging token changes, to support Personalization push notification campaigns using Firebase Cloud Messaging.

You do not normally need to call this method. If your app uses Firebase Messaging, simply ensure your FIRMessagingDelegate defines the method messaging:didReceiveRegistrationToken:.

1- (void)setFirebaseToken:(nonnull NSString *)token

Parameters

Availability

1.3.0

Discussion

By default, Personalization will swizzle your FIRMessagingDelegate’s messaging:didReceiveRegistrationToken: method, if defined. However, if you disable swizzling in the Info.plist, you will need to manually call this method.

This method will have no effect if you don’t enable support for push notifications. For more information, see [EVGClientConfigurationBuilder usePushNotifications].

Personalization will only send push notifications to the most recent user. For more information, see [Evergage userId].

Personalization automatically tracks clicks and opens for typical push notifications. However, when you need to call a method to track a click, use [EVGContext trackClickthrough:actionIdentifier:].

For more information, see Push Notifications.

See Also

• [EVGClientConfigurationBuilder usePushNotifications]
• [Evergage userId]
• [EVGContext trackClickthrough:actionIdentifier:]
• setAPNSToken:

You do not normally need to call this method. If your app uses push notifications, simply ensure you receive them by defining a notification-received method.

1- (void)handleNotification:(nullable NSDictionary *)notification actionIdentifier:(nullable NSString *)actionIdentifier

Availability

1.3.0

Discussion

By default, Personalization will swizzle any of these notification-received methods you define:

• UNUserNotificationCenterDelegate userNotificationCenter:didReceiveNotificationResponse:withCompletionHandler:
• UIApplicationDelegate application:didReceiveRemoteNotification:
• UIApplicationDelegate application:didReceiveRemoteNotification:fetchCompletionHandler:
• UIApplicationDelegate application:handleActionWithIdentifier:forRemoteNotification:completionHandler:
• UIApplicationDelegate application:handleActionWithIdentifier:forRemoteNotification:withResponseInfo:completionHandler:

However, if you disable swizzling in the Info.plist (see swizzlingEnabled), then you will need to manually call this method from your notification-received method.

This method notifies Personalization when the app receives/processes a notification, so Personalization can update campaign attribution statistics.