Register Contacts with Marketing Cloud Engagement

To register contacts and devices with Marketing Cloud Engagement, work with your marketer to decide on your contact key strategy, optionally set the contact key yourself, and check required registration fields.

Prerequisite

Ensure that the SDK is configured and initialized successfully. For guidance on configuring and initializing the SDK, refer to the Quickstart Guide.

Determine Your Contact Key Strategy

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

You can choose to set the contact key yourself via the SDK, or you can choose not to set the contact key at all. If you don’t set the contact key via the SDK, the Engagement servers assign the contact a random GUID as the contact key. Review the following 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.

Collaborate with your marketing team to determine your target audience and contact key strategy.

Target Audience

Determine whether to send messages to:

Anonymous users exclusively
Known users exclusively
Both anonymous and known users

Contact Key

Determine the identifier to be used as the contact key.

Message Targeting and Contact Key Timing

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, login, and so on), 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.

Note

Contact Key Selection

Set the contact key to a specific value provided by your end user or to a unique identifier that your business uses for the contact. You could use details such as a customer ID, mobile number, email address, loyalty number, or another value that you’ve retrieved from the user or your own servers.

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.

When setting the contact key, ensure the following.

The contact key must not be null or an empty string.
The contact key must not have leading or trailing whitespaces.
After it's set, you can change the contact key for a contact, but you can't clear it.
Don't set the contact key to a generic, non-unique value.

Set the Contact Key

Skip this step if you want to send only to anonymous users and want Engagement to set a random GUID as the contact key.

Note

For setting the contact key, review the following examples for Android and iOS. If you choose to reuse this example code in your implementation, ensure that you replace user@mycompany.com in the example with the contact key of your choice.

SFMCSdk.requestSdk { sfmcSdk ->
    // Set contact key for all modules
    sfmcSdk.identity.setProfileId("uniquelyIdentifyingKey")
    // OR set contact key only for the Mobile Push module
    sfmcSdk.identity.setProfileId("uniquelyIdentifyingKey", ModuleIdentifier.PUSH)
    // Retrieve the contact key
    sfmcSdk.mp {
      val contactKey = it.moduleIdentity.profileId
    }
  }

// Set contact key for all modules
SFMCSdk.identity.setProfileId("user@mycompany.com")
// OR set contact key only for the Mobile Push module
SFMCSdk.identity.setProfileId([ModuleName.push: "user@mycompany.com"])
// Retrieve the contact key
SFMCSdk.requestPushSdk { mp in
    let contactKey = mp.contactKey()
}

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.

Tip

Check Required Registration Fields

Invalid registrations can cause the device to be set to an inactive or opted-out state in Engagement. To prevent invalid registrations, ensure that your implementation is sending the required fields, applicable optional fields, and that they’re properly formed by following these steps.

To ensure that you’re correctly sending all required fields, review the SDK state (Android, iOS).
Review the required fields in the following table against what you find logged in debug mode (Android, iOS).
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 ascertain whether it successfully processed it. The SDK also can't know whether the registration was marked invalid by the server.

Note

The following is an example registration request.

{
  "deviceID" : "1EB8C21D-CA72-41AC-930D-CEC9A311D699",
  "device_Token" : "t22wrs6vr221rr29r671412s5vwuruwwsu8s48rs274t7tr3s771w7t9v32vus41",
  "sdk_Version" : "8.0.8",
  "app_Version" : "32.1.4",
  "dST" : true,
  "location_Enabled" : true,
  "proximity_Enabled" : true,
  "push_Enabled" : true,
  "platform_Version" : "15.6",
  "timeZone" : "-14400",
  "quietPushEnabled" : false,
  "subscriberKey" : "contactkey@example.com",
  "platform" : "iOS",
  "hwid" : "iPhone13",
  "etAppId" : "	995k5k1j-162l-4n5m-j4lo-jl5mmnk14n47",
  "locale" : "en_US",
  "tags" : [
    "ALL",
    "DEBUG",
    "DISCOUNT",
    "IOS"
  ],
  "attributes" : [
    {
      "key" : "CODE",
      "value" : "FREE99"
    }

  "registrationId" : "1eb8c21d-ca72-41ac-930d-cec9a311d699",
  ],
  "language" : "en_US",
}

The following table lists the various fields that are used while registering contacts with Engagement.

Field	Requirement	Type	Description
`access_token`	Required	String	The SDK was configured or initialized with this value. Value provided when the app is created in MobilePush Administration in Engagement. Required to authenticate with Engagement.
`deviceID`	Required	String	Automatically generated random GUID that identifies a device. Represents a unique installation of the app.
`etAppId`	Required	String	Unique ID for the app registered with Engagement. SDK was configured or initialized with this value. Created when the app is registered in MobilePush Administration in Engagement.
`platform`	Required	String	Device’s operating system. Valid values are iOS and Android.
`device_token`	Optional	String	Troubleshooting Note: The unique token that Apple or Google FCM returns to the SDK is essential for push notifications. To prevent implementation issues, don’t customize or interrupt the process by which the PNS returns the device token to the SDK. Tampering with the device token can prevent it from being valid. A valid device token must be submitted to Engagement for the device to receive push notifications.
`push_enabled`	Optional	Boolean	Troubleshooting Note: Denotes whether the device/contact is eligible to receive push messages. A value of true means that the device/contact is opted in. If omitted, the API assumes push_enabled = true. A value of “true” must be submitted to Engagement in order for Engagement to send push notifications to this device.
`subscriberKey`	Optional	String	Value that contains the subscriber key for a user. Captured or provided by the app. If it isn’t captured or provided, Engagement generates and randomly assigns a GUID to the app. Up to 100 characters.
`attributes`	Optional	Array of key:value pair objects	Troubleshooting Note: Before the SDK can submit values for attributes, which are the keys in the pair, first define attributes in the MobilePush Demographics table in Contact Builder. If there’s a mismatch between the attribute name that the SDK submits vs. what’s defined in Contact Builder, then Engagement rejects the entire registration.
`dst`	Optional	Boolean	Determines whether the device time zone honors daylight saving time.
`timezone`	Optional	String	Time zone offset in seconds, as set by the app.
`tags`	Optional	Array of strings	Labels used to group or segment which devices to send to.
`platform_version`	Optional	String	Version of the device’s operating system
`badge`	Optional	Integer	The current number displayed on the app icon via badge (iOS only). Represents the number of unread messages.
`sdk_version`	Optional	String	Version of the SDK integrated with the app.
`app_version`	Optional	String	Version of the app that’s on the device.
`location_enabled`	Optional	Boolean	Denotes whether the subscriber allows the app to track their location. A value of true means that the app can track location.
`hwid`	Optional	String	Hardware identifier used to identify device model and type.
`locale`	Optional	String	Language code used by the device.
`proximity_enabled`	Optional	Boolean	Denotes whether the subscriber allowed the app to range for beacons. A value of true means that the subscriber allows ranging for beacons.

Register Contacts with Marketing Cloud Engagement

Prerequisite

Determine Your Contact Key Strategy

Message Targeting and Contact Key Timing

Contact Key Selection

Set the Contact Key

Check Required Registration Fields

No Results