Managing user information

In addition to the information automatically collected and stored for each of a user’s clients, an appUser itself can have metadata and profile information attached to it, in order to better understand the context and the history of the user.

Profile information can be added to a user in two ways:

There are two types of profile information fields: structured and unstructured.

Structured Fields

Structured fields are properties that Smooch has identified as common across many use cases, and has exposed as common properties across all users, when present. The currently supported structured fields are:

  • givenName, also referred to as firstName in some contexts, which represents the user’s given name
  • surname, also referred to as lastName in some contexts, which represents the user’s surname
  • signedUpAt, which is the date when the user first started using your service, or when they first became a customer. If not customized, this field is automatically populated to be the date the user was created in Smooch, which is most likely the moment when the user messaged you for the first time.
  • email, which represents the user’s email address. Note that this field is only used for display purposes, and does not affect how Smooch delivers messages in any way. For information on how to link an email address to a user to be able to send them messages over email, see the business initiated conversations guide.

Example

{
    "appUser": {
        "_id": "deb920657bbc3adc3fec7963",
        "givenName": "Steve",
        "surname": "Brule",
        "email": "steveb@channel5.com",
        "signedUpAt": "2015-10-08T23:52:11.677Z"
    }
}

Unstructured Fields

Unstructured fields, also referred to as “custom properties”, are a set of key/value pairs that are specific to your application domain, or use case. These fields are stored under the properties field of an appUser, and can have values of type Number, String, or Boolean.

Example

{
    "appUser": {
        "_id": "deb920657bbc3adc3fec7963",
        "properties": {
          "premiumUser": true,
          "numberOfPurchases": 20,
          "itemsInCart": 3,
          "couponCode": "PREM_USR"
        }
    }
}

Setting user profile information

Adding properties using the REST API

To add properties via the REST API, call the Update App User endpoint:

curl https://api.smooch.io/v1.1/apps/5963c0d619a30a2e00de36b8/appusers/c7f6e6d6c3a637261bd9656f \
     -X PUT \
     -d '{"givenName": "Steve", "properties": {"premiumUser": true, "numberOfPurchases": 20, "itemsInCart": 3, "couponCode": "PREM_USR"}}' \
     -H 'content-type: application/json' \
     -H 'authorization: Bearer your-account-jwt'

Adding properties using the SDKs

Each of Smooch’s web and mobile SDKs (iOS, Android, and Web) support attaching properties to a user at runtime. The details of when and how these properties are uploaded to the server is handled automatically by the SDKs, so in general you should not need to worry about this detail. However, the process is documented here for completeness.

On Android and iOS, when a user property is set using one of the SDK methods, the properties are immediately serialized to disk until they can be uploaded to the server. Changes to user properties are uploaded in batches at regular intervals while the app is in the foreground, as well as just before the app is sent to the background, or immediately before a message is sent by the user. If the application exits unexpectedly, or the user has intermittent internet connection or no internet connection, the properties will remain on disk until the upload eventually succeeds (even across app launches). If the user does not yet exist (i.e. the user has not yet sent their first message, and the startConversation method has not been called), the properties are still tracked and stored on disk until the user is eventually created, and they will be uploaded as part of the user creation flow.

On Web, the user properties are stored in memory, and uploaded in batches at regular intervals, or immediately before a message is sent by the user. If the user does not yet exist (i.e. the user has not yet sent their first message, and the startConversation method has not been called), the properties are still tracked and stored in memory until the user is eventually created, and they will be uploaded as part of the user creation flow. In contrast to the Android and iOS SDKs, the Web Messenger does not store any user property information on disk - if the browser window is closed before the user is created, then the properties will be discarded.

Examples

iOS

Objective-C

#import <Smooch/Smooch.h>

[SKTUser currentUser].firstName = @"Steve";
[SKTUser currentUser].lastName = @"Brule";
[SKTUser currentUser].email = @"steveb@channel5.com";
[SKTUser currentUser].signedUpAt = [NSDate date];
[[SKTUser currentUser] addProperties:@{
                           @"premiumUser": @YES,
                           @"numberOfPurchases": @20,
                           @"itemsInCart": @3,
                           @"couponCode": @"PREM_USR"
                           }];

Swift

SKTUser.current()?.firstName = "Steve"
SKTUser.current()?.lastName = "Brule"
SKTUser.current()?.email = "steveb@channel5.com"
SKTUser.current()?.signedUpAt = NSDate() as Date
SKTUser.current()?.addProperties([
    "premiumUser": true,
    "numberOfPurchases": 20,
    "itemsInCart": 3,
    "couponCode": "PREM_USR"
])

Android

Java

import io.smooch.core.User;

User.getCurrentUser().setFirstName("Steve");
User.getCurrentUser().setLastName("Brule");
User.getCurrentUser().setEmail("steveb@channel5.com");
User.getCurrentUser().setSignedUpAt(new Date(1420070400000l));

final Map<String, Object> customProperties = new HashMap<>();
customProperties.put("premiumUser", true);
customProperties.put("numberOfPurchases", 20);
customProperties.put("itemsInCart", 3);
customProperties.put("couponCode", "PREM_USR");
User.getCurrentUser().addProperties(customProperties);

Web Messenger

Javascript

Smooch.updateUser({
    givenName: 'Steve',
    surname: 'Brule',
    email: 'steveb@channel5.com',
    signedUpAt: Date.now(),
    properties: {
      premiumUser: true,
      numberOfPurchases: 20,
      itemsInCart: 3,
      couponCode: 'PREM_USR'
    }
});