Register Contacts

To register contacts and devices, work with your marketing team to decide on your contact key strategy. Set all the required registration fields.

Configure the SDK and initialize it. See the Quickstart Guide.

A contact key is a unique identifier that represents an individual in Marketing Cloud and is required when sending messages. In Marketing Cloud Engagement, the contact key is used to map and unify an individual’s identity across Email, MobileConnect, and MobilePush. Contact key is also used to unify, aggregate, and help identify your contact’s devices in Engagement.

You can use the SDK to set the contact key yourself. If you don’t use the SDK to set a contact key, the application assigns the contact a random GUID as the contact key. Review these use cases and implications for each choice.

Partner with your marketer to determine your contact key strategy. Your strategy can influence your approach to implementing the registration of contacts and devices. It’s also important to decide on your contact key strategy because frequently changing a user’s contact key isn’t good practice. Additionally, such changes often lead to contacts being disassociated or orphaned from a device. It can also cause confusion when sending to contacts, and during troubleshooting implementation and billing cycles.

Work with your marketing team to determine whether to send messages to anonymous users only, known users only, or both. Also, determine which identifier to use as the contact key.

Send to both anonymous and known users: To send to both anonymous and known users, set the contact key after you’ve identified the user (after they create an account and log in), but don’t delay registrations. Sending to both anonymous and known users can cause contacts to become disassociated from a device (orphaned), but your marketer can manage these contacts in Engagement.
Send only to known users: To send only to known users, set the contact key yourself, and delay registration of anonymous users in the SDK until the contact key is set. Delaying registration until after the user is known prevents contacts from being disassociated from a device.
Send only to anonymous users: To send only to anonymous users, don’t set the contact key, and don’t delay registrations.

For guidance on delaying registrations, see Delay Registrations Until Contact Key is Set.

Set the contact key to a specific value provided by your end user or to a unique identifier. You can use details such as a customer ID, mobile number, email address, loyalty number, or another value.

Ideally, this value must be the same identifier that your company uses to identify the user across other Engagement channels such as email, SMS, or chat messaging.

The contact key must meet these requirements:

It can’t be null or an empty string.
It can’t have leading or trailing whitespaces.
After it’s set, you can change the contact key for a contact, but you can’t clear it.
It must be a unique value.

Skip this step if you want to send only to anonymous users. The contact key for an anonymous user is a random GUID.

To set the contact key, review these examples for Android and iOS. If you use this example code in your implementation, replace user@example.com in the example with the contact key of your choice.

If you use version 10 of the SDK, use this code.

For earlier versions of the SDK, use this code.

For version 10 of the SDK, use this code.

For earlier versions of the SDK, use this code.

Update the locally stored contact record only while your app is in the foreground, not while it’s in the background. This practice optimizes API calls to Engagement servers. If your app is in the background, the SDK initializes to show a notification or to pre-cache messages, resulting in unnecessary communication with Engagement servers.

A registration is considered invalid if it doesn’t contain all the required fields, or if there are errors in the required fields. If a registration is invalid, the device is set to an inactive or opted-out state.

To verify that the registration information is properly recorded, review how to test and validate registrations.

Registrations are asynchronous. While the SDK can receive a successful 201 response from the server indicating that it received the registration, it can’t determine whether it successfully processed it. The SDK also can’t know whether the server marked the registration as invalid.

This code sample shows an example of a registration request.

For earlier versions of the SDK, use this code.

This table lists the fields that Marketing Cloud Engagement uses when it registers contacts.

Field	Type	Description
`access_token`	String	Required. The value that was provided when the app was created in Marketing Cloud Setup. The SDK was configured or initialized with this value.
`deviceID`	String	Required. A random GUID that identifies a device, representing a unique installation of the app.
`etAppId`	String	Required. A unique ID for the app that was created when the app was set up in Marketing Cloud. The SDK was configured or initialized with this value.
`platform`	String	Required. The device’s operating system. Possible values are `iOS` and `Android`.
`device_token`	String	The unique token that Apple or Google FCM returns to the SDK. To prevent implementation issues, don’t customize or interrupt the process by which the notification service returns the device token to the SDK. Tampering with the device token can invalidate it. The app must send a valid device token to Marketing Cloud for the device to receive push notifications.
`push_enabled`	Boolean	Indicates whether the device or contact is eligible to receive push messages. If the value is `true`, the device or contact is opted in. Only opted-in contacts or devices receive push notifications. The default value is `true`.
`subscriberKey`	String	The subscriber key for a user, which is captured or provided by the app. The key can contain up to 100 characters. If this value isn’t provided, a random GUID is generated.
`attributes`	Array of key-value pairs	A set of attributes that apply to a contact. Before your app submits attributes, define the attribute keys in the MobilePush Demographics table in Contact Builder. If the attribute name that the SDK submits doesn't match the attribute name defined in Contact Builder, the entire registration is rejected.
`dst`	Boolean	Indicates whether the device time zone honors daylight saving time.
`timezone`	String	The time zone offset in seconds, as set by the app.
`tags`	Array of strings	A set of labels used to group or segment which devices to send to.
`platform_version`	String	The version of the device’s operating system
`badge`	Integer	The current number displayed in a badge on the app icon (iOS only). Represents the number of unread messages.
`sdk_version`	String	The version of the SDK integrated with the app.
`app_version`	String	The version of the app that’s on the device.
`location_enabled`	Boolean	Indicates whether the subscriber allows the app to track their location. If the value is `true`, the app can track the user’s location.
`hwid`	String	A hardware identifier used to identify device model and type.
`locale`	String	The locale code used by the device.
`proximity_enabled`	Boolean	Indicates whether the subscriber allowed the app to range for beacons. If the value is `true`, the subscriber allowed ranging for beacons.