ÃÛ¶¹ÊÓƵ

DocumentationCampaignCampaign technotes

[v7]{class="badge informative" title="Also applies to Campaign Classic v7"} [v8]{class="badge positive" title="Applies to Campaign v8"}

Push Notification Channel changes push-upgrade

Last update: Wed Sep 18 2024 00:00:00 GMT+0000 (Coordinated Universal Time)

CREATED FOR:

  • Experienced
  • Admin

You can use Campaign to send push notifications on iOs and Android devices. To perform this, Campaign relies on mobile application subscription services.

Some important changes to the Android Firebase Cloud Messaging (FCM) service are released in 2024, and may impact your ÃÛ¶¹ÊÓƵ Campaign implementation. Your subscription services configuration for Android push messages may need to be updated to support this change.

In addition, ÃÛ¶¹ÊÓƵ highly recommends to move to the token-based connection to APNs rather than a certicate-based connection, which is more secure and scalable.

Google Android Firebase Cloud Messaging (FCM) service fcm-push-upgrade

What changed? fcm-changes

As part of Google’s continual effort to improve its services, the legacy FCM APIs will be discontinued on July 22, 2024. Learn more about Firebase Cloud Messaging HTTP protocol in .

ÃÛ¶¹ÊÓƵ Campaign Classic v7 and ÃÛ¶¹ÊÓƵ Campaign v8 already support the latest APIs to send push notification messages. However, some old implementations still rely on the legacy APIs. These implementations must be updated.

Are you impacted? fcm-impact

If your current implementation supports subscription services connecting to FCM using the legacy APIs, you are impacted. Transition to the latest APIs is mandatory to avoid any service distruption. In that case, ÃÛ¶¹ÊÓƵ teams will reach out to you.

To check if you are impacted, you can filter your Services and Subscriptions as per the filter below:

  • If any of your active push notification service uses the HTTP (legacy) API, your setup will be directly impacted by this change. You must review your current configurations and move to the newer APIs as described below.

  • If your setup exclusively uses the HTTP v1 API for Android push notifications, then you are already in compliance and no further action will be required on your part.

How to update? fcm-transition-procedure

Prerequisites fcm-transition-prerequisites

  • The Android Firebase Admin SDK service’s account JSON file is needed to have the mobile application moved to HTTP v1. Learn how to get this file in .

  • For Campaign Classic v7, the support of HTTP v1 has been added in 20.3.1 release. If your environment is running on an older version, a prerequisite for the transition to HTTP v1 is to upgrade your environment to the latest Campaign Classic build. For Campaign v8, HTTP v1 is supported by all releases, and no upgrade is needed.

  • As a Campaign Classic v7 on-premise user, you must upgrade both the Marketing and Real-Time execution servers.

  • For Hybrid, Hosted and Managed Cloud Services deployments, in addition to the transition procedure below, contact ÃÛ¶¹ÊÓƵ to update your Real-Time (RT) execution server.

  • About the Android routing external account:

    • As a Campaign Classic v7 on-premise or hybrid user, check that your Android routing external account is configured with androidPushConnectorV2.js. Learn more in Campaign Classic v7 documentation.

    • For Hybrid, Hosted and Managed Cloud Services deployments, you must also connect with ÃÛ¶¹ÊÓƵ Customer Care team to validate that the androidPushConnectorV2.js (nms) connector is selected in Android routing external account of your Mid sourcing server.

Transition procedure fcm-transition-steps

To move your environment to HTTP v1, follow these steps:

  1. Browse to your list of Services and Subscriptions.

  2. List all mobile applications using the HTTP (legacy) API version.

  3. For each of these mobile applications, set the API version to HTTP v1.

  4. Click the Load project json file to extract project details… link to load directly your JSON key file.

    You can also enter manually the following details:

    • Project Id
    • Private Key
    • Client Email

  5. Click Test the connection to check that your configuration is correct and that the marketing server has access to the FCM. Note that for Mid-Sourcing deployments, the Test connection button cannot check if the server has access to the Android Firebase Cloud Messaging (FCM) service.

  6. As an option, you can enrich a push message content with some Application variables if needed. These are fully customizable and a part of the message payload sent to the mobile device.

  7. Click Finish then Save.

    Below are the FCM payload names to further personalize your push notification. These options are detailed here.

    table 0-row-3 1-row-3 2-row-3 1-align-center 2-align-center 3-align-center 5-align-center 6-align-center 7-align-center 9-align-center 10-align-center 11-align-center
    Message type Configurable message element (FCM payload name) Configurable options (FCM payload name)
    data message N/A validate_only
    notification message title, body, android_channel_id, icon, sound, tag, color, click_action, image, ticker, sticky, visibility, notification_priority, notification_count validate_only
NOTE
Once these changes are applied in all your server, all new Push notification deliveries to Android devices use the HTTP v1 API. Existing push deliveries in retry, in progress, and in use, still use the HTTP (legacy) API. Learn how to update them in the section below.

Update existing templates fcm-transition-update

Once transition HTTP v1 is done, you must update your delivery templates for Android push notifications to increase the number of batch messages. To do this, browse to your Android delivery template’s properties and, in the Delivery tab, set the Message Batch quantity to 256. Apply this change to all delivery templates used for your Android deliveries, and to all your existing Android deliveries.

You can also update existing deliveries and delivery templates created before the upgrade to a version supporting HTTP v1. To perform this:

  • As a Managed Cloud Services or Hosted customer, contact ÃÛ¶¹ÊÓƵ to update your existing Android delivery templates.

  • For on-premise environments, download the fcm-httpv1-migration.js script, and run it as detailed below.

    Download fcm-httpv1-migration.zip.

    note caution
    CAUTION
    The script must be executed on your on-premise Marketing instance.
    accordion
    Steps to update existing deliveries and templates (on-premise only)

    To patch all deliveries and deliveries templates created before the upgrade to a version supporting HTTP v1, follow these steps:

    1. Export your existing deliveries and delivery templates in a package to be able to restore them in case of an unexpected problem occured during the patching.

    2. Run the following command in Posgresql:

      code language-sql 
      pg_dump -Fp -f /sftp/<db_name>-nmsdelivery-before_rd_script.sql -t nmsdelivery -d <db_name>

    3. By default the script is in dryrun mode, you can launch it in that mode to check if some delivery needs to be patched.

      Command

      code language-sql 
      nlserver javascript -instance:<instance_name> -file fcm-httpv1-migration.js

      Output

      code language-sql 
      ...
HH:MM:SS >   Processing delivery (id:123456,  label:'Deliver on Android - New', name:'DM1234')
HH:MM:SS >   Dry run: Would update androidCheckParams for delivery (id:123456,  label:'Deliver on Android - New', name:'DM1234')
HH:MM:SS >   Processing delivery (id:567890,  label:'Deliver on Android - New', name:'DM5678')
HH:MM:SS >   Dry run: Would update androidCheckParams for delivery (id:567890,  label:'Deliver on Android - New', name:'DM5678')
...
HH:MM:SS >   Summary (XYZ processed deliverie(s) or delivery template(s)):
HH:MM:SS >>  - X had not patchable androidCheckParams formula!
HH:MM:SS >   - Y had androidCheckParams formula patched.
HH:MM:SS >   - Z ignored as alreading having androidCheckParams formula patched.
      note note
      NOTE
      The not patchable deliveries need to be updated manually. Their ID can be found in the log.

    4. Run the script in execution mode the following way to update deliveries:

      code language-sql 
      nlserver javascript -instance:<instance_name> -file fcm-httpv1-migration.js -arg:run

What is the impact for my Android apps? fcm-apps

There are no specific changes required to the Android Mobile applications’ code and the notification behavior should not change.

However, with HTTP v1, you can further personalize your push notification with HTTPV1 additional options.

You can:

  • Use the Ticker field to set the ticker text of your notification.
  • Use the Image field to set the image’s URL to be displayed in your notification.
  • Use the Notification Count field to set the number of new unread information to display directly on the application icon.
  • Set the Sticky option to false so that the notification is automatically dismissed when the user clicks it. If set to true, the notification is still displayed even when the user clicks it.
  • Set the Notification Priority level of your notification to default, minimum, low or high.
  • Set the Visibility level of your notification to public, private or secret.

For more on the HTTP v1 additional options and how to fill these fields, refer to .

Apple iOS Push Notification service (APNs) apns-push-upgrade

What changed? ios-changes

As recommended by Apple, you should secure your communications with Apple Push Notification service (APNs) by using stateless authentication tokens.

Token-based authentication offers a stateless way to communicate with APNs. Stateless communication is faster than certificate-based communication because it doesn’t require APNs to look up the certificate, or other information, related to your provider server. There are other advantages to using token-based authentication:

  • You can use the same token from multiple provider servers.

  • You can use one token to distribute notifications for all of your company’s apps.

Learn more about Token-based connections to APNs in .

ÃÛ¶¹ÊÓƵ Campaign Classic v7 and ÃÛ¶¹ÊÓƵ Campaign v8 support both token-based and certificate-based connections. If your implementation relies on a certificate-based connection, ÃÛ¶¹ÊÓƵ highly recommends you to update it to a token-based connection.

Are you impacted? ios-impact

If your current implementation relies on certificate-based requests to connect to APNs, you are impacted. Transition to a token-based connection is recommended.

To check if you are impacted, you can filter your Services and Subscriptions as per the filter below:

  • If any of your active push notification service uses the Certificate-based authentication mode (.p12), your current implementations should be reviewed and moved to a Token-based authentication mode (.p8) as described below.

  • If your setup exclusively uses the Token-based authentication mode for iOS push notifications, then your implementation is already up-to-date and no further action will be required on your part.

How to update? ios-transition-procedure

Prerequisites ios-transition-prerequisites

  • For Campaign Classic v7, the support of Token-based authentication mode has been added in 20.2 release. If your environment is running on an older version, a prerequisite for this change is to upgrade your environment to the latest Campaign Classic build. For Campaign v8, Token-based authentication mode is supported by all releases, and no upgrade is needed.

  • You need an APNs authentication token signing key to generate the tokens that your server uses. You request this key from your Apple developer account, as explained in .

  • For Hybrid, Hosted and Managed Services deployments, in addition to the transition procedure below, contact ÃÛ¶¹ÊÓƵ to update your Real-Time (RT) execution server. The Mid-Sourcing server is not impacted.

  • As a Campaign Classic v7 on-premise user, you must upgrade both the Marketing and Real-Time execution servers. The Mid-Sourcing server is not impacted.

Transition procedure ios-transition-steps

To move your iOS mobile applications to the Token-based authentication mode, follow these steps:

  1. Browse to your list of Services and Subscriptions.

  2. List all mobile applications using the Certificate-based authentication mode (.p12).

  3. Edit each of these mobile applications, and browse to the Certificate/Private key tab.

  4. From the Authentication Mode drop-down, select Token-based authentication mode (.p8).

  5. Fill in the APNs connection settings Key Id, Team Id and Bundle Id then select your p8 certificate by clicking Enter the private key….

  6. Click Test the connection to check that your configuration is correct and that the server has access to APNs. Note that for Mid-Sourcing deployments, the Test connection button cannot check if the server has access to APNs.

  7. Click Next to start configuring the production application and follow the same steps as detailed above.

  8. Click Finish then Save.

Your iOS application is now moved to the Token-based authentication mode.

recommendation-more-help
c14bd44c-7b5f-474a-888d-1c2baee5a247