Create User Profile

This document will cover the methods to create a user and set channel preferences

Pre-requisites

Integrate Go SDK

How Suprsend identifies a user

Suprsend identifies a user by a unique identifier distinct_id. The identifier for a user is important as we use this key to create user profile and all the information related to a user, like channel preferences, is attached to that profile. You can view user profile by searching distinct_id on Subscribers page

Please note: you cannot change a user's id once it has been set, so we recommend you use a non-transient id like primary key in your DB rather than phone number or email address.


Step 1 : Create a new user

To create a new user or to update an existing user's profile, you'll have to first instantiate the user object. Call suprClient.Users.GetInstance to instantiate the user object.

user := suprClient.Users.GetInstance("__distinct_id__") // Unique identifier of user in your application

// Save user
_, err = user.Save()
if err != nil {
  log.Fatalln(err)
}



Step 2: Set Communication Channel preferences

Communication Channel Preference decides whether a user will receive communication on a particular channel or not. Setting Channel preferences means that whenever you are triggering a workflow, the communication will be sent on the channels set in user profile (given that the template for that channel is present in the template group).

Especially for event based workflow triggers, where you just pass the user's distinct_id and the communication channels are picked from user profile

📘

Set Channel Preference for event based workflows

In event based workflows, since you only pass user's distinct_id in your track event call, you'll have to add channel preference first in the user profile before making the call.


1. Add User Channels

Use user.Add_* method(s) to add user channels in a profile

user := suprClient.Users.GetInstance("__distinct_id__") // Unique identifier of user in your application

// Add email channel
user.AddEmail("[email protected]")

// add sms channel
user.AddSms("+1444455555")

// Add whatsapp channel
user.AddWhatsapp("+1444455555")

// Add androidpush token, token providers: fcm/xiaomi
user.AddAndroidpush("__fcm_push_token__", "fcm")

// Add iospush token, token providers: apns
user.AddIospush("__ios_push_token__", "apns")

// Add webpush token (vapid)
user.AddWebpush(map[string]interface{}{
  "keys": map[string]interface{}{
    "auth":   "",
    "p256dh": "",
  },
  "endpoint": "",
}, "vapid")

// Save user
_, err = user.Save()
if err != nil {
  log.Fatalln(err)
}




2. Remove User Channels

Use user.Remove_* method(s) to remove channels from a user profile

user := suprClient.Users.GetInstance("__distinct_id__") // Unique identifier of user in your application

// remove email channel
user.RemoveEmail("[email protected]")

// remove sms channel
user.RemoveSms("+1444455555")

// remove whatsapp channel
user.RemoveWhatsapp("+1444455555")

// remove androidpush token
user.RemoveAndroidpush("__fcm_push_token__", "fcm")

// remove iospush token
user.RemoveIospush("__ios_push_token__", "apns")

// remove webpush token
user.RemoveWebpush(map[string]interface{}{
  "keys": map[string]interface{}{
    "auth":   "",
    "p256dh": "",
  },
  "endpoint": "",
}, "vapid")

// Save user
_, err = user.Save()
if err != nil {
  log.Fatalln(err)
}



3. Remove User Channels in bulk

If you need to delete/unset all emails (or any other channel) of a user, you can call user.Unset() method on the user instance. The method accepts the channel key/s (a single key or list of keys)

user := suprClient.Users.GetInstance("__distinct_id__") // Unique identifier of user in your application

// If you need to remove all emails for this user, call user.Unset(["$email"])
user.Unset([]string{"$email"})

// # what value to pass to unset channels
// # for email:                $email
// # for whatsapp:             $whatsapp
// # for SMS:                  $sms
// # for androidpush tokens:   $androidpush
// # for iospush tokens:       $iospush
// # for webpush tokens:       $webpush
// # for slack:                $slack

// Save user
_, err = user.Save()
if err != nil {
  log.Fatalln(err)
}



🚧

Note

After calling Add_*/Remove_*/Unset methods, don't forget to call user.Save(). On call of Save(), SDK sends the request to SuprSend platform to update the User Profile.


Add Preferences in User Profile

You can also set custom properties in user profile that is used to set user preferences


Set Preferred language

If you want to send notification in user's preferred language, you can set it by passing language code in user.SetPreferredLanguage() method. This is useful especially for the applications which offer vernacular or multi-lingual support.

user := suprClient.Users.GetInstance("__distinct_id__") // Unique identifier of user in your application

// Set user preferred language. languageCode must be in [ISO 639-1 2-letter] format
user.SetPreferredLanguage("en")

// Save user
_, err = user.Save()
if err != nil {
  log.Fatalln(err)
}




Response

When you call user.Save(), the SDK internally makes an HTTP call to SuprSend Platform to register this request, and you'll get an error message if something fails


Bulk API for handling multiple user profiles

To update user profiles in bulk, use Bulk users API. There isn't any limit on number-of-records that can be added to BulkUsers instance.

Use .Append() on BulkUsers instance to add however-many-records to call in bulk.

// create bulkUsers instance
bulkIns := suprClient.BulkUsers.NewInstance()

// Prepare user1
user1 := suprClient.Users.GetInstance("__distinct_id1__")
user1.AddEmail("[email protected]")
user1.AddWhatsapp("+1909090900")

// prepare user 2
user2 := suprClient.Users.GetInstance("__distinct_id2__")
user2.AddEmail("[email protected]")
user2.AddWhatsapp("+2909090900")

// Append all users to bulk instance
bulkIns.Append(user1, user2)

// Call save
bulkResponse, err := bulkIns.Save()
if err != nil {
  log.Fatalln(err)
}
log.Println(bulkResponse)

How SuprSend Processes the bulk API request

  • On calling bulkIns.Save(), the SDK internally makes one-or-more Callable-chunks.
  • Each callable-chunk contains a subset of records, the subset calculation is based on each record's bytes-size and max allowed chunk-size, chunk-length etc.
  • For each callable-chunk SDK makes an HTTP call to SuprSend to register the request.

Response

Response is an instance of suprsend.BulkResponse type

// Response structure

suprsend.BulkResponse{
  Status : "success",
  Total : 10, // number of records sent in bulk
  Success : 10, // number of records succeeded
  Failure : 0, // number of records failed
  FailedRecords : [],
}

suprsend.BulkResponse{
  Status : "fail",
  Total : 10, // number of records sent in bulk
  Success : 0, // number of records succeeded
  Failure : 10, // number of records failed
  FailedRecords : [{"record": {...}, "error": "error_str", "code": 500}]
}

suprsend.BulkResponse{
  Status : "partial",
  Total : 10, // number of records sent in bulk
  Success : 6, // number of records succeeded
  Failure : 4, // number of records failed
  FailedRecords : [{"record": {...}, "error": "error_str", "code": 500}]
}

Other user methods

Set preferred language

If you want to send notification in user's preferred language, you can set it by passing language code in this method. This is useful especially for the applications which offer vernacular or multi-lingual support.

user.SetPreferredLanguage("en")

Set preferred timezone

You can set timezone of user using this method. Value for timezone must be from amongst the IANA timezones.

user.SetTimezone("America/Los_Angeles")

Set

Set is used to set the custom user property or properties. The given key and value will be assigned to the user, overwriting an existing property with the same key if present.

user.SetKV("prop", "value")
user.Set(map[string]interface{}{"prop1": "val1", "prop2": "val2"})
user.set("name", "user")

user.set({
  "prop1": "val1", 
  "prop2": ["one", "two", "three"], 
  "number": 20
})
Parameterstype
keystring (shouldn't start with ss_ or $)
valueany

Set Once

Works just like user.set, except it will not override already existing property values. This is useful for properties like first_login_date.

user.set_once(key, value);
user.set_once({ key1: value1, key2: value2 });
user.set_once("first_login", "2021-11-02")

user.set_once({"first_login" : "2021-11-02", "DOB" : "1991-10-02"})

Append

This method will append a value to the list for a given property.

user.SetOnceKV("prop4", "val4")
user.SetOnce(map[string]interface{}{"prop3": "val3"})
user.append("wishlist", "iphone12")

user.append({"wishlist" : "iphone12"})

Remove

This method will remove a value from the list for a given property.

user.RemoveKV(k, v)
user.Remove({k1: v1, k2, v2})
user.remove("wishlist", "iphone12")

user.remove({"wishlist" : "iphone12"})

Increment

Add the given number to an existing property on the user. If the user does not already have the associated property, the amount will be added to zero. To reduce a property, provide a negative number for the value.

user.IncrementKV("increment_prop", 2)
user.Increment(map[string]interface{}{"increment_prop1": 5})
user.increment("login_count", 1)

user.increment({"login_count" : 1, "order_count" : 1})
Parameterstype
keystring (shouldn't start with ss_ or $)
valuenumber (+ or -)

Unset

This will remove a property permanently from user properties.

user.Unset([]string{"$email"})
user.unset("wishlist")

user.unset(["wishlist", "cart"])
Parameterstype
keysstring or array of strings (shouldn't start with ss_ or $)