Updating User Profiles

A user's Iterable profile contains descriptive information about them: demographic info, preferences, etc. You can use this data to create dynamic lists and customize the messages you send (by referencing user profile data with Handlebars).

# In this article

# Limitations

User profiles have a soft limit of 1,000 fields. If you think you'll need more fields, talk to your Iterable Customer Success Manager.

# How to make the updateUser call

Here's some sample code that makes an updateUser call:

Swift

// The IterableAPI.updateUser(...) can be called anywhere the SDK is accessible
// myFunc() demonstrates this usage
import IterableSDK

func myFunc() {
    let dataField: [String: Any] = [
        "Address": [
            "Street1": "123 Main St",
            "Street2": "Apt 1",
            "City": "Iter-a-ville",
            "State": "CA",
            "Zip": "90210"
        ]
    ]
    
    IterableAPI.updateUser(dataField,
                           mergeNestedObjects: false,
                           onSuccess: myUserUpdateSuccessHandler,
                           onFailure: myUserUpdateFailureHandler)
}

func myUserUpdateSuccessHandler(data: [AnyHashable: Any]?) -> () {
    print("Successfully sent user update request to Iterable")
}

func myUserUpdateFailureHandler(reason: String?, data: Data?) -> () {
    print("Failure sending user update request to Iterable")
}

Objective-C

// The [IterableAPI updateUser:...] can be called anywhere the SDK is accessible
// myFunc demonstrates this usage
@import IterableSDK;

typedef void (^successHandler)(NSDictionary * _Nullable);
typedef void (^failureHandler)(NSString * _Nullable, NSData * _Nullable);

- (void)myFunc {
    NSDictionary<NSString *, id> *data = @{
        @"Address": @{ @"Street1": @"123 Main St",
                       @"Street2": @"Apt 1",
                       @"City": @"Iter-a-ville",
                       @"State": @"CA",
                       @"Zip": @"90210"
        }
    };
    
    [IterableAPI updateUser:data
         mergeNestedObjects:NO
                  onSuccess:myUserUpdateSuccessHandler
                  onFailure:myUserUpdateFailureHandler];
}

successHandler myUserUpdateSuccessHandler = ^(NSDictionary * _Nullable data) {
    NSLog(@"Successfully sent user update request to Iterable");
};

failureHandler myUserUpdateFailureHandler = ^(NSString * _Nullable reason, NSData * _Nullable data) {
    NSLog(@"Failure sending user update request to Iterable");
};

Java

JSONObject address = new JSONObject();
JSONObject datafields = new JSONObject();

try {
    address.put("Street1", "123 Main St");
    address.put("Street2", "Apt 1");
    address.put("City", "Iter-a-ville");
    address.put("State", "CA");
    address.put("Zip", "90210");

    datafields.put("dataFields", address);
} catch (JSONException e) {
    e.printStackTrace();
}

IterableApi.getInstance().updateUser(datafields);

Now, in your messages, you can reference the user's City (or any other field) with Handlebars, like this:

{{Address.City}}

# How mergeNestedObjects works

mergeNestedObjects determines whether Iterable should merge nested objects included in an updateUser request with analogous objects on the user's profile, or overwrite that data. mergeNestedObjects defaults to false.

For example, consider a user profile that includes the following object:

"settings": {
    "mobile": true
}

Then, assume that an updateUser call includes a similar object:

"settings": {
    "email": true
}

If updateUser sets mergeNestedObjects to false (the default value), the resulting user profile value is:

"settings": {
    "email": true
}

However, if updateUser sets mergeNestedObjects to true, the resulting user profile value is:

"settings": {
    "mobile": true,
    "email": true
}

# When to make the updateUser call

Call updateUser when a user has:

• Updated their personal information.
• Completed a key step in an onboarding or sales process. For example, you might want to set completedOnboarding to true, or assign a value to a field that's useful for segmentation (setting testGroup to testGroupA or something similar).
• Completed a key step in your onboarding, sales or retargeting process. For example, you may want to add "completedOnboarding": true or "testGroup": "A" to the user profile for later segmentation, splitting the users down different journeys or analyzing later for test comparisons.

# Tracking anonymous users

To track anonymous users in Iterable, provide a userId. If your project uses email as the only unique identifier, then this causes Iterable to generate a placeholder email for the user—read Handling Anonymous Users for more info).

# Taking a user from anonymous to known

Iterable can convert anonymous users to known users. The example function below updates the current user's email and userId. You will likely want to use this code when your user signs in or self-identifies when signing up.

Swift

let email = "newEmail@example.com"

// The IterableAPI.updateUser(...) can be added to any method within your code. `yourUserIsNowKnownFunction` is just an example
func yourUserIsNowKnownFunction() {
    IterableAPI.updateEmail(email,
                            onSuccess: myUserUpdateSuccessHandler,
                            onFailure: myUserUpdateFailureHandler)
}

func myUserUpdateSuccessHandler(data: [AnyHashable: Any]?) -> () {
    print("Successfully sent user update request to Iterable")
}

func myUserUpdateFailureHandler(reason: String?, data: Data?) -> () {
    print("Failure sending user update request to Iterable")

    IterableAPI.email = email

    IterableAPI.updateUser(dataField, mergeNestedObjects: false)
}

Objective-C

@import IterableSDK;

typedef void (^successHandler)(NSDictionary * _Nullable);
typedef void (^failureHandler)(NSString * _Nullable, NSData * _Nullable);

NSString *email = @"newEmail@example.com";

// The [IterableAPI updateUser:...] can be added to any method within your code. `yourUserIsNowKnownFunction` is just an example
- (void)yourUserIsNowKnownFunction {
    [IterableAPI updateEmail:email 
        onSuccess:myUserUpdateSuccessHandler 
        onFailure:myUserUpdateFailureHandler];
}

successHandler myUserUpdateSuccessHandler = ^(NSDictionary * _Nullable data) {
    NSLog(@"Successfully sent user update request to Iterable");
};

failureHandler myUserUpdateFailureHandler = ^(NSString * _Nullable reason, NSData * _Nullable data) {
    NSLog(@"Failure sending user update request to Iterable");
    
    IterableAPI.email = email;

    [IterableAPI updateUser:dataField mergeNestedObjects:false];
};

Java

final String email = "newEmail@example.com";

IterableApi.getInstance().updateEmail(email, new IterableHelper.SuccessHandler() {
    @Override
    public void onSuccess(JSONObject data) {
        System.out.println("sent to Iterable success");

    }
}, new IterableHelper.FailureHandler() {
    @Override
    public void onFailure(String reason, JSONObject data) {
        System.out.println("sent to Iterable failure");
        IterableApi.getInstance().setEmail(email);
        //This assumes your saving your user profile fields in the datafield object locally
        IterableApi.getInstance().updateUser(datafields);
    }
});

There is a chance the updateEmail call will fail. The most likely reason is that the user already exists so we should now update the user call directly in the onFailure handler.