Reconnect App Push Notifications Integration

To send Reconnect personalized Push Notifications to your Android and iOS native app users, you must do the following: 

• Step 1: Integrate your Firebase account with Reconnect. In Experience OS, set up the Firebase account you use with your app, and retrieve the Firebase service account key file.
• Step 2: Manage opted-in users. Inform Dynamic Yield which users consent to receive messages.
• Step 3: Track engagement. Measure the success of your campaigns.

Step 1: Integrate Firebase

Set up your Firebase account in Reconnect

Prerequisite: A Firebase account integrated with your application.

To create the integration in Reconnect:

1. In the Integrations tab, click Create Channel Integration, and then select App Push Notifications.
2. Select the Firebase option.
3. Upload your Service Account Key file. Learn how to retrieve the file in the next section.
   Note the following:
   • The file is available to download in your project in Firebase.
   • Must be a JSON file.
4. Click Validate & Save. The file contents are validated against Firebase services. If the validation fails, an error is displayed and the file is removed. If the validation is successful, the integration is saved and is ready to use.

Retrieve the Firebase service account key file

To retrieve the Firebase key file, you must create a new service account and then generate the token. 

Step 1: Create a new service account in Firebase

In your project in Firebase, do the following:

1. Go to Project Overview › Project Settings.
2. In either the Cloud Messaging or Service accounts tab, select Manage Service Accounts.
   This takes you to the Google Cloud console (console.cloud.google.com).
3. Click + Create Service Account.
   
4. Enter a name for the service account (for example: DY, DYServiceAccount, or DynamicYield).
5. Enter your service account ID.
6. Optionally, enter a description for clarity. For example: “For push notifications using DY services”.
   
7. Click Create and Continue.

Step 2: Define an access role and generate the token

1. In the Grant this service account access to project area, click Pick a Predefined Role, and then select one of the following roles, which have the cloudmessaging.messages.create permission (to learn more about roles, see Understanding Roles in the Firebase documentation):
   • Firebase Admin (roles/firebase.admin): Grants broad permissions across all Firebase services, including Firebase Cloud Messaging. Allows the account to send push notifications, but is over-permissive for just FCM-related operations.
   • Firebase Grow Admin (roles/firebase.growthAdmin): Provides permissions across several Firebase services that are related to growth, like Firebase Cloud Messaging and Firebase Remote Config.
   • Firebase Admin SDK Administrator Service Agent (roles/firebase.sdkAdminServiceAgent): Allows service accounts to act as Firebase Admin SDKs. It isn't specifically designed for FCM but might include the necessary permissions.
   • Firebase SDK Provisioning Service Agent (roles/firebase.sdkProvisioningServiceAgent): Designed to provision and manage SDK configurations. It's not necessarily directly related to sending FCM messages.
2. Click Continue and then Done.
3. In the actions menu next to the service account (3 vertical dots), select Manage keys.
4. Click + ADD KEY and then select JSON.
5. A JSON key is generated and downloaded. Provide this key to Dynamic Yield in the integration as described in the set up the integration section.

Useful Firebase documentation

The following are important docs with information about the fields contained in notifications sent using the Firebase Admin SDK (color, image, click link, title, body):

• https://firebase.google.com/docs/reference/fcm/rest/v1/projects.messages
• https://firebase.google.com/docs/cloud-messaging/send-message#customize-messages-across-platforms
• https://firebase.google.com/docs/cloud-messaging/concept-options 

Step 2: Manage your opted-in users

Notify Dynamic Yield about users who gave your app permission to send push notifications on their device, using the Update Reconnect Opt-In server-side event. It is very important to also notify when they withdraw permission, using the Reconnect Opt-Out server-side event.

How it works

In addition to the Firebase token (pushID), Dynamic Yield also collects the user's DYID. When both values are shared with us via the Reconnect Opt In API, we perform an internal identification, so that when the DYID performs an action on the app (say, add to cart) Reconnect knows to trigger a notification to the matching pushID (Firebase token).

Send an Opt In event

When a user subscribes to push notifications on your site, fire the Update Reconnect Opt-In server-side event: 

POST /v2/userdata/channels/app-push/opt-in

Headers: { 
  "accept": "application/json", 
  "content-type": "application/json", 
  "dy-api-key": "your-api-key" // section ID inside 
} 

Body: { 
  "associatedDevice": { 
    "dyid": "" 
  }, 

  "identifier": { 
    "type": "pushID"   // only 'pushID' is supported for push channels 
    "value": ""  // User token generated by Firebase  
  } 
} 

Send an Opt Out event

When a user unsubscribes from marketing emails on your site, fire the Update Reconnect Opt-Out server-side event: 

POST /v2/userdata/channels/app-push/opt-out

Headers: { 
  "accept": "application/json", 
  "content-type": "application/json", 
  "dy-api-key": "your-api-key" // section ID inside 
} 

Body: { 
  "associatedDevice": { 
    "dyid": "" 
  }, 

  "identifier": { 
    "type": "pushID"   // only 'pushID' is supported for push channels 
    "value": ""  // User token generated by Firebase  
  } 
} 

Step 3: Track engagement

Reporting App Push notification clicks

Reconnect uses a ${Push tracking} variable to enable click tracking on App Push notifications. This variable contains unique data for each message, which must be sent back to Dynamic Yield as is via the user engagement API.

There are 2 ways to include this variable:

• Use one of our out-of-the-box templates: If you use one of Reconnect’s built-in templates, the ${Push tracking} variable is already included in the notification payload.
• Use a custom template (blank variation): If you create your own notification template from scratch, you must manually add the ${Push tracking} variable under the data object of the Firebase notification call. This ensures that Reconnect can generate and deliver the unique tracking payload.

Handling click events in your app

When you include the ${Push tracking} variable in your payload, your mobile app will:

1. Listen for notification click events using your Firebase Messaging client.
2. Extract the tracking payload from the notification’s data.tracking field.
3. Send the payload back to Reconnect as a PN_CLICK event (the payload must be sent exactly as received).

Example of a PN_CLICK event payload:

curl --request POST \
  --url https://dy-api.com/v2/collect/user/engagement \
  --header 'accept: application/json' \
  --header 'content-type: application/json' \
  --header 'dy-api-key: your-api-key' \
  --data '{
    "user": {
      "active_consent_accepted": false,
      "dyid": "-5123123123",
      "dyid_server": "-51234123123"
    },
    "session": {
      "dy": "123456"
    },
    "engagements": [
      {
        "type": "PN_CLICK",
        "trackingData": {
          "rri": "132123123",
          "sectionID": "9872626",
          "reqTs": "12312312312312",
          "userID": "4656722918296846673",
          "version": "2",
          "events": [
            {
              "ver": "101482916",
              "expVisitId": "4032971100745578591",
              "smech": "1",
              "vars": ["101098971", "1014654644"],
              "exp": "1296028",
              "mech": "1"
            },
            {
              "ver": "101482916",
              "expVisitId": "4032971100745578591",
              "smech": "2",
              "vars": ["101098971"],
              "exp": "1296028",
              "mech": "1"
            }
          ]