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 are properties that Sunshine Conversations 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 namesurname, also referred to as lastName in some contexts, which represents the user’s surnameemail, which represents the user’s email address. Note that this field is only used for display purposes, and does not affect how 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 outbound messaging guide.avatarUrl, which represents the user’s avatarsignedUpAt, 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 Sunshine Conversations, which is most likely the moment when the user messaged you for the first time.Example
{
"appUser": {
"_id": "deb920657bbc3adc3fec7963",
"givenName": "Steve",
"surname": "Brule",
"email": "steveb@channel5.com",
"avatarUrl": "https://s3.amazonaws.com/avatar.jpg",
"signedUpAt": "2015-10-08T23:52:11.677Z"
}
}
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"
}
}
}
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' \
--user 'keyId:keySecret'
Each of Sunshine Conversations’ 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 createConversation 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 createConversation 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.
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"
])
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);
JavaScript
Smooch.updateUser({
givenName: 'Steve',
surname: 'Brule',
email: 'steveb@channel5.com',
signedUpAt: Date.now(),
properties: {
premiumUser: true,
numberOfPurchases: 20,
itemsInCart: 3,
couponCode: 'PREM_USR'
}
});