Migrating push tokens

A push token is a unique key, created and assigned by Apple or Google to create a connection between an app and an iOS, Android, or web device. Push token migration is the importing of those already-generated keys into Braze’s platform.

Braze customers who were previously sending push notifications, either on their own or with a different provider, often have a list of users with registered push tokens.

To continue sending push messages to these users during the Braze SDK integration process, you can import these tokens into Braze and target those users using Braze’s campaign tool.

Migration via API

Push tokens can either be uploaded for identified users or anonymous users. This means that either an external_id needs to present, or the anonymous users must have the push_token_import flag set to true.

The app_id required can be found in the Developer Console, under the API Settings tab in the Identification section. Each app (iOS, Android, Web, etc.) has its own app_id - be sure to use the correct platform’s app_id.

Migration if external ID is present

1
2
3
4
5
6
7
8
9
10
11
12
"attributes" : [
  {
	"push_token_import" : false,
	"external_id": "external_id1",
	"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

These tokens can be migrated by importing them with our API.

To do this, use the users/track endpoint and post the following information:

1
2
3
4
5
6
7
8
"attributes" : [
  {
	"push_token_import" : true,
	"push_tokens": [
	  { "app_id": "", "token": "", "device_id": "" }
	]
  }
]

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
"attributes": [ 
  {
    "push_token_import" : true,
	"email": "braze.test1@testbraze.com",
	"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": "braze.test2@testbraze.com",
	"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"}  
	]
  }
]

When specifying push_token_import as true:

• external_id and braze_id should not be specified
• The attribute object must contain a push token
• If the token already exists in Braze, the request is ignored; otherwise, Braze will create a temporary, anonymous user profile for each token to enable you to continue to message these individuals

After import, as each 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 login to the device with said push token, we will do nothing.

Web push tokens

Web push tokens contain extra fields that other platforms do not. As a result, we recommend that you integrate push and allow your token-base to repopulate naturally.

Sending push before Braze SDK integration (Android only)

If you find that you must send a push notification to your users before the Braze SDK integration is complete, you can 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 is contingent on the specific push partner you used before Braze.

Last updated on June 1, 2021