Push Notifications

Marketing Cloud Personalization supports Push Notification campaigns for iOS apps using:

• Apple Push Notification System (APNs)
• Firebase Cloud Messaging (FCM)

Generating and Configuring APNs Certificates 

For Personalization Push Notification campaigns to work on your iOS apps, you need to generate APNs certificates and configure Personalization to use those certificates.

1. Access your Apple Developer Certificates and click + in the top right corner.
2. Select one of the APNs SSL options (Sandbox or Sandbox & Production) and click Continue.
3. Select the app and click Continue.
4. Follow the instructions to create and complete the Certificate Signing Request.
5. Download and install the certificate on your Mac.
6. Open Keychain Access from the same Mac.
7. Click on My Certificates and find the app’s Push Services certificate you just created.
8. Check whether the private key is attached to the certificate by clicking the arrow icon to the left of the certificate name.
9. Right-click the certificate and click Expose….
10. Name the file and select .p12 as the File Format.
11. (Optional) Enter a password and click Save.

To upload the APNs certificate and private key .p12 file to Personalization, do the following.

1. Log in to the Personalization UI and select the Dataset.
2. From the left-hand menu, click Mobile > your app, and then Mobile Push Setup.
3. Depending on whether your certificate is Sandbox-only, Production-only, or Sandbox and Production, enter the password for the .p12 file (if any) in the appropriate fields.
4. Click Upload p12 File and choose your file to upload.
5. Click Save.

If you’re using Personalization to send push notifications to your app via FCM, you’ll need to provide an FCM private key JSON file. To obtain your FCM private key JSON file and then add it to Personalization, do the following.

1. Open your Firebase Cloud Messaging console for your app.

2. Navigate to Project Overview > Project settings > Cloud Messaging.

3. Click Manage Service Accounts.

4. Click + CREATE SERVICE ACCOUNT.

   The default service account is assigned the Firebase Admin SDK Administrator Service Agent role that provides more access than necessary. To limit access and enhance security, we recommend creating a service account with only the Firebase Cloud Messaging API Admin role.

   Note

5. Provide appropriate values for Service account name, Service account ID, and Service account description.

6. Click CREATE AND CONTINUE.

7. Under Select a role, search for and select the Firebase Cloud Messaging API Admin role. This role includes the cloudmessaging.messages.create permission, which is the only “write” permission required.

8. Click CONTINUE.

9. Optionally, grant users access to this service account.

10. Click DONE.

11. Under the Actions column for the newly-created service account, click Manage keys.

12. Click ADD KEY > Create new key.

13. Select JSON as the Key type and click CREATE. The private key JSON file is now saved to our computer. Ensure that you’ve stored the files appropriately and click CLOSE.

14. Log in to the Personalization UI and select the Dataset.

15. From the left-hand menu, click Mobile > your app > Mobile Push Setup.

16. Under Firebase Cloud Messaging (FCM), upload your private key JSON file.

17. Click Save.

Additionally, you’ll need to provide your APNs certificate to Firebase. For guidance, see Set up a Firebase Cloud Messaging client app on Apple platforms.

If you’ve provided credentials for both APNs and Firebase, you must pick which one to use when the app is next added to any push notification campaign. Personalization will only send notifications through one channel to prevent duplicating notifications.

Important

Setting Up Your App to Use APNs and Firebase 

To set up your app to use APNs and Firebase Cloud Messaging, do the following.

• Set up the app to use APNs

  • Enable the Push Notifications capability and register your app with APNs, as described in Apple’s User Notifications documentation.

  • Prompt users for desired notification settings using the requestAuthorizationWithOptions:completionHandler: method.

    This permission is required for Personalization to accept push tokens via [Evergage(Swizzling) setAPNSToken:] and [Evergage(Swizzling) setFirebaseToken:]. During the first app launch, the user hasn’t yet granted permission. Hence, it’s likely that token callbacks and rejections occur before the user accepts the permissions. Therefore, if obtaining push tokens as soon as possible is critical for you rather than waiting until the next app launch, ensure that token callbacks are retriggered in this completionHandler, or set directly.

    • If using APNS, you can trigger [Evergage(Swizzling) setAPNSToken:] via another call to registerForRemoteNotifications on UIApplication.
    • If using Firebase Cloud Messaging, you can directly call [Evergage(Swizzling) setFirebaseToken:] with the current token obtained from Firebase Cloud Messaging’s FCMToken property.

• If your app uses Firebase Cloud Messaging, refer to Set up a Firebase Cloud Messaging client app on Apple platforms for set up instructions.

  Ensure that you configure Firebase and set the Messaging delegate before starting Personalization. For startup example code, refer to the Evergage class documentation.

  Important

• To allow the collecting and sending of users’ APNS or Firebase tokens to Personalization, your app must opt-in to Personalization push notification campaigns. For more information, see [EVGClientConfigurationBuilder usePushNotifications]. For example code, refer to the Evergage class documentation.

• Your app should define the callbacks that receive tokens so that Personalization can also start listening. For more information, see [Evergage(Swizzling) setAPNSToken:] and [Evergage(Swizzling) setFirebaseToken:].

• Your app should also define the callbacks that receive notifications. For more information, see [Evergage(Swizzling) handleNotification:actionIdentifier:].

Additional Details

• Personalization can send push notifications to the most recent users only. For more information, see [Evergage userId].
• For information on how to ensure campaign click-tracking when you’re app receives push notifications while foregrounded, uses UNNotificationCenterDelegate, and you decide to render custom UI to the user, see [EVGContext trackClickthrough:actionIdentifier:].

Next 

• For campaign-authoring guidance, see Push Campaign Best Practices.
• For information on testing your campaigns, see the Testing guide.
• To set up mobile data campaigns for your app, see Mobile Data Campaigns.