Evergage(Swizzling) Category Reference
Declared in |
---|
Evergage+Swizzling.h |
"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
.
- See
-
Push Notifications
- APNS token
- For more information, see
setAPNSToken:
. Your app must still declare the delegate method to allow Personalization to "listen" as well.
- For more information, see
- Firebase token
- For more information, see
setFirebaseToken:
. Your app must still declare the delegate method to allow Personalization to "listen" as well.
- For more information, see
- 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.
- For more information, see
- This swizzling can be disabled, see
swizzlingEnabled
.
- APNS token
-
UIViewController
-
viewDidAppear:
andviewWillDisappear:
. 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.
-
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
swizzlessetDelegate:
. When Personalization sees the first non-nil delegate, itdispatch_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.
- If the delegate already exists, Personalization
Below you can see a simplified version of how Personalization swizzles a method. Personalization also takes precautions to try or catch NSExceptions
, etc.
If swizzling is enabled for the Personalization iOS SDK.
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.
Parameters
Parameters | Description |
---|---|
url | The URL that the app is opening via application:openURL:options: (iOS9+) , application:openURL:sourceApplicatoin:annotation: , or application:handleOpenURL: . |
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 theExpID
, 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:
In addition to default behavior of showing mobile campaigns in the
Published
state, also show mobile campaigns that are in theTest
state. All campaign rules will still be active. -
Test a Specific Experience:
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:
Return to the default behavior of showing mobile campaigns in the
Published
state only.
See Also
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 methodapplication:didRegisterForRemoteNotificationsWithDeviceToken:
. - Your app calls
registerForRemoteNotifications
onUIApplication
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.
Parameters
Parameters | Description |
---|---|
token | The APNS token as received from iOS. |
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:
.
Personalization also supports APNS with or without Firebase, and requires an APNS token even when using Firebase. For more information, see setAPNSToken:
.
Parameters
Parameters | Description |
---|---|
token | The Firebase token. |
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.
Parameters | Description |
---|---|
notification | The notification or userInfo as received from iOS. |
actionIdentifier | The actionIdentifier from the notification, if any. |
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.