Skip to content

Install/User Tagging

Contextual allows you to add attributes to your user for personalisation and targeting or creating real-time segments.

Sh_cuid

The sh_cuid is a very important concept in Contextual. The sh_cuid is a tag, that uniquely identifies a User. You have to set this tag from the client SDKs (iOS, Android). We encourage you to use an ID that is meaningful to you - an email address, an account number etc.

If you are concerned about privacy, then you can also use a magic identifier, hash or UUID - just as long as this is in your backend.

The sh_cuid will be used to link Users in your backend to our backend. If multiple Installs are identified by the same sh_cuid, all of them will be tagged. If an Install is identified by the same sh_cuid later, the tags will not be copied automatically. You will have to do it manually. Setting a tag twice will override the first tag.

From your app

To tag users from your app place the following snippet just after your registration and login calls.

IOS

SWIFT: 

1
2
//unique id in your system, for example customer's login id
   Contextual.sharedInstance().tagUserId("user@example.com")

OBJECTIVE-C: 

1
2
//unique id in your system, for example customer's login id
    [CONTEXTUAL tagUserId:@"user@example.com"];

Android

KOTLIN or JAVA: 

1
2
//unique id in your system, for example customer's login id
  Contextual.tagUserId("user@example.com")

From your back end

Use this API to create and/or update one or more tags for one or more sh_cuids.

Authentication: Must use the App Key and the Auth Token that can be found on the Settings Page

EndPoint: /v3/tags/

Method: POST, Content-Type: application/json

The POST payload is a dictionary like the following:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
curl 'https://api.contextu.al/v3/tags/' \
-H 'Authorization: Token <your token from Dashboard/Settings>' \
-H 'Content-Type: application/json'  \
-d @- << EOF 
{
    "app_key": "MyAppKey",
    "sh_cuid": "myuser@acme.com",
    "key": "nickname",
    "string": "mynickname"
}
EOF
Parameter Example Description
sh_cuid user12345@gmail.com, md5(email), <id> See above
key "nickname", "level", "joined" The tag's name. Limit: 30 characters.
string "somestring" A string value to tag the "key" with.
numeric 42 A numeric value to tag the "key" with.
datetime '2015-01-27T05:57:31.399861+00:00' A datetime value in isoformat to tag the "key" with.

Response:

In case all tags were correct, the server returns the following JSON response and HTTP Code 200:

1
2
3
{
"status": "OK"
}

In case of any errors the HTTP Code will be != 200 and the response will look like the following: 

1
2
3
{
"__all__": ["list", "of", "generic", "errors"]
}

Even if one or more tags failed to be inserted and an error is returned, other tags that have been submitted correctly are still processed. The index (starting from 0) indicates which dictionary(ies) had issues.

Last update: 2024-01-15