Identifying the User

The Iterable SDK can identify users by email or user ID.

# In this article

# Overview

To identify a user, you'll need to do two things: specify an email address or user ID, and then call updateUser to send that value to Iterable.

# Identifying the user by email

Email is typically used as the key identify within Iterable because it tracks across devices to aggregate data between a user's phones, tablet, web-site activity or even IoT (Internet-of-Things) device.

Iterable also allows for multi-dimensional nested data types, meaning you can organize your data based on relevant key values.

Once you have an email address or user ID for your app's current user, set IterableAPI.email or IterableAPI.userId. For example:

Add this line of code as soon as you know the user's email:

Swift

IterableAPI.email = "user@example.com"

Objective-C

IterableAPI.email = @"user@example.com";

Java

IterableApi.getInstance().setEmail("user@example.com");

# Identifying the user by user ID

Iterable can also identify user by user ID. However, all things being equal, it is recommended to use email as the key identifier.

Swift

IterableAPI.userId = "user123"

Objective-C

IterableAPI.userId = @"user123";

Java

IterableApi.getInstance().setUserId("user123");

You can add the userId identifier at any point after the IterableConfig() call.

# Identifying the device of the user

For Iterable to send push notifications to an iOS device, it must know the unique token assigned to that device by Apple or Android.

Iterable uses silent push notifications to tell iOS apps when to fetch new in-app messages from the server. Because of this, your app must register for remote notifications with Apple even if you do not plan to send it any push notifications.

# Auto push registration

IterableConfig.autoPushRegistration determines whether or not the SDK will:

• Automatically register for a device token when the SDK is given a new email address or user ID. Disable the device token for the previous user when a new user logs in.

If IterableConfig.autoPushRegistration is true (the default value):

• Setting IterableAPI.email or IterableAPI.userId causes the SDK to automatically call the registerForRemoteNotifications() method on UIApplication and pass the resulting device token to the application(_:didRegisterForRemoteNotificationsWithDeviceToken:) method on the app delegate.

If IterableConfig.autoPushRegistration is false:

• After setting IterableAPI.email or IterableAPI.userId, you must manually call the registerForRemoteNotifications() method on UIApplication. This will fetch the device token from Apple and pass it to the application(_:didRegisterForRemoteNotificationsWithDeviceToken:) method on the app delegate.

# Send the device token to Iterable

To send the device token to Iterable and save it on the current user's profile, call IterableAPI.register(token:) from the application(_:didRegisterForRemoteNotificationsWithDeviceToken:) method on UIApplicationDelegate. For example:

Swift

func application(_ application: UIApplication, didRegisterForRemoteNotificationsWithDeviceToken deviceToken: Data) {
    IterableAPI.register(token: deviceToken)
}

Objective-C

- (void)application:(UIApplication *)application didRegisterForRemoteNotificationsWithDeviceToken:(NSData *)deviceToken {
    [IterableAPI registerToken:deviceToken];
}

Java

// Iterable SDK automatically registers the push token with Iterable 
// whenever setEmail or setUserId is called.

// If you want to trigger token registration manually, first disable automatic 
// registration by calling setAutoPushRegistration(false) on IterableConfig.Builder when initializing the SDK.

// Then call registerForPush whenever you want to register the token:

// Only use this line if you want to register push manually.
// IterableApi.getInstance().registerForPush();

Once you register for push, you should see the device on the user's Iterable profile. Access a user's profile in Iterable by navigating to Audiences > Contact Lookup.

# Updating email and user ID

Use the following code to update both an email and a userId:

Swift

IterableAPI.updateEmail("<NEW-EMAIL-ADDRESS>",
    onSuccess: { _ in
        IterableAPI.updateUser(
            [JsonKey.userId: "<NEW-USER-ID>"],
            mergeNestedObjects: false,
            onSuccess: { _ in
            // this needs to be set after both calls have finished successfully
            IterableAPI.userId = "<NEW-USER-ID>"
        }, onFailure: nil)
}, onFailure: nil)

Objective-C

[IterableAPI updateEmail:@"<NEW-EMAIL-ADDRESS>"
                onSuccess:^(NSDictionary * _Nullable data) {
    [IterableAPI updateUser:@{@"userId": @"<NEW-USER-ID>"}
            mergeNestedObjects:NO
                    onSuccess:^(NSDictionary * _Nullable data) {
        // this needs to be set after both calls have finished successfully
        IterableAPI.userId = @"<NEW-USER-ID>";
    } onFailure:nil];
} onFailure:nil];

Java

IterableApi.getInstance().updateEmail("newEmail@somewhere.com", new IterableHelper.SuccessHandler() {
    @Override
    public void onSuccess(JSONObject data) {
        JSONObject userIDobj = new JSONObject();
        try {
            userIDobj.put("userId", "newUserId");
        } catch (JSONException e) {
            e.printStackTrace();
        }
        IterableApi.getInstance().updateUser(userIDobj);
    }
}, new IterableHelper.FailureHandler() {
    @Override
    public void onFailure(String reason, JSONObject data) {
        Log.e(TAG, reason)
    }
});

# Next steps

To troubleshoot user identification, see Testing and Troubleshooting User Profiles.

If you have already identified the user for your use case, see Updating User Profiles and User Update Recommendations.