Migrating push tokens

A push token is a unique anonymous identifier that specifies where to send an app’s notifications. Braze connects with push service providers like Firebase Cloud Messaging Service (FCMs) for Android and Apple Push Notification Service (APNs) for iOS, and those providers send unique device tokens that identify your app. If you were sending push notifications prior to integrating Braze, either on your own or through another provider, push token migration allows you to continue sending push notifications to your users with registered push tokens.

Automatic migration via SDK

The Braze SDK will automatically migrate the push token of a user who has previously opted into your push notifications the first time they sign into your Braze-integrated app or site. If you integrate the Braze SDKs, you will not need to migrate push tokens using the API.

However, because push tokens migrate when a user first logs into your app, note that Braze will not be able to send push notifications to users who have not logged in after your SDK integration. You may still wish to manually migrate Android and iOS push tokens as a way to re-engage with these users.

Manual migration via API

Manual push token migration is the process of importing these previously-created keys into your Braze platform through the API.

Programmatically migrate iOS (APNs) and Android (FCM) tokens to your platform by using the users/track endpoint. You can migrate both identified users (users with an associated external ID) and anonymous users (users without an external ID).

Specify your app’s app_id during push token migration to associate the appropriate push token with the appropriate app. Each app (iOS, Android, etc.) has its own app_id, which can be found in the Identification section of the API Keys page. Be sure to use the correct platform’s app_id.

Migration if external ID is present

For identified users, set the push_token_import flag to false (or omit the parameter) and specify the external_id, app_id, and token values in the user attributes object.

For example:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
curl --location --request POST 'https://rest.iad-01.braze.com/users/track' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR-API-KEY-HERE' \
--data-raw '{
  "attributes" : [
    {
      "push_token_import" : false,
      "external_id": "example_external_id",
      "country": "US",
      "language": "en",
      "YOUR_CUSTOM_ATTRIBUTE": "YOUR_VALUE",
      "push_tokens": [
        {"app_id": "APP_ID_OF_OS", "token": "PUSH_TOKEN_STRING"}
      ]
    }
  ]
}'

Migration if external ID is not present

When importing push tokens from other systems, an external_id is not always available. In this circumstance, set your push_token_import flag as true and specify the app_id and token values. Braze will create a temporary, anonymous user profile for each token to enable you to continue to message these individuals. If the token already exists in Braze, the request is ignored.

For example:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
curl --location --request POST 'https://rest.iad-01.braze.com/users/track' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR-API-KEY-HERE' \
--data-raw '{
  "attributes": [ 
    {
      "push_token_import" : true,
      "email": "[email protected]",
      "country": "US",
      "language": "en",
      "YOUR_CUSTOM_ATTRIBUTE": "YOUR_VALUE",
      "push_tokens": [
        {"app_id": "APP_ID_OF_OS", "token": "PUSH_TOKEN_STRING", "device_id": "DEVICE_ID"}
      ]
    },
      
    {
      "push_token_import" : true,
      "email": "[email protected]",
      "country": "US",
      "language": "en",
      "YOUR_CUSTOM_ATTRIBUTE_1": "YOUR_VALUE",
      "YOUR_CUSTOM_ATTRIBUTE_2": "YOUR_VALUE",
      "push_tokens": [
        {"app_id": "APP_ID_OF_OS", "token": "PUSH_TOKEN_STRING", "device_id": "DEVICE_ID"}  
      ]
    }
  ]
}'

After import, when the anonymous user launches the Braze-enabled version of your app, Braze will automatically move their imported push token to their Braze user profile and clean up the temporary profile.

Braze will check once a month to find any anonymous profile with the push_token_import flag that doesn’t have a push token. If the anonymous profile no longer has a push token, we will delete the profile. However, if the anonymous profile still has a push token, suggesting that the actual user has yet to log in to the device with said push token, we will do nothing.

Importing Android push tokens

If you must send Android push notifications to your users before the Braze SDK integration is complete, use key-value pairs to validate push notifications.

You must have a receiver to handle and display push payloads. To notify the receiver of the push payload, add the necessary key-value pairs to the push campaign. The values of these pairs are contingent on the specific push partner you used before Braze.

Last updated on December 5, 2022