Message state tracking

The Tracker API allows, in part, for managing the state of a message, such as whether or not the user has viewed the message.

Tracking message state

As messages are interacted with, it is the responsibility of the consumer to inform accesso’s services that something happened. The Tracker API is designed for this purpose. The two tracker events most relevant to messaging are Read and LinkedTapped.

Message Read tracker events

The message Read tracker event informs accesso’s services that a particular message has been viewed by the end-user. This event should be raised when the user opens the message in a mobile app.

1
2
3
4
5
6
7
8
9
10
11
12
13
curl -i -X PUT \
  https://api.{region}.te2.io/rest/tracker/track \
    -H 'Authorization: Bearer {token}' \
    -H 'Content-Type: application/json' \
    -d '{
        "eventType": "message",
        "appId": "{appId}",
        "messageId": "{messageId}",
        "action": "Read",
        "version": "{version}",
        "id": "{id}",
        "appUserId": "{appUserId}"
    }'

Where:

• appId: A unique key to identify the calling application. This is provided by accesso account management when a new application is registered. A single accesso account can support multiple applications, and each application can be restricted to a subset of venues. The appId determines which venues may interact with this device. Omitting the appId or providing an unrecognized appId will result in an error.
• messageId: The ID of the message that was read. This value can be obtained from the id attribute of the message from the messages API.
• version: The version of the mobile app or other client software presenting the message to the user.
• id: A unique key to identify this call to the API. This is typically a GUID.
• appUserId: A unique key to identify the user device. Every user device must have a unique appUserId. If the device is a mobile application or responsive web site, this is typically a GUID generated at install time or on first use. For wearable devices, this can be a radio ID or other hardware identifier.

Message LinkTapped tracker events

The message LinkTapped tracker event informs accesso’s services that the end-user clicked a link or button embedded within a message.

1
2
3
4
5
6
7
8
9
10
11
12
13
14
curl -i -X PUT \
  https://api.{region}.te2.io/rest/tracker/track \
    -H 'Authorization: Bearer {token}' \
    -H 'Content-Type: application/json' \
    -d '{
        "eventType": "messageLinkTapped",
        "appId": "{appId}",
        "messageId": "{messageId}",
        "action": "LinkTapped",
        "version": "{version}",
        "linkId": "{linkId}",
        "id": "{id}",
        "appUserId": "{appUserId}"
    }'

Where linkId is the index of the link object present in the message’s links array. The remaining attributes are described above.

For example, consider the message:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
{
    "msgId": "abc123",
    "id": "abc123",
    "links": [
        {
            "isDefault": false,
            "label": "X",
            "target": "target1",
            "type": "Button"
        },
        {
            "isDefault": false,
            "label": "Y",
            "target": "target2",
            "type": "Button"
        }
    ],
    // ...snip...
}

If button X is pressed, then the request issued will be:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
curl -X PUT \
  https://api.{region}.te2.io/rest/tracker/track \
    -H 'Authorization: Bearer {token}' \
    -H 'Content-Type: application/json' \
    -d '{
        "linkId": "0",                # link at index 0
        "eventType": "messageLinkTapped",
        "appId": "TE2Happyland_1.0",
        "messageId": "abc123",
        "action": "LinkTapped",
        "version": "1.0",
        "id": "7c63aa02-cd65-4f08-b9be-4fddd0545aee",
        "appUserId": "023b96ee-8aec-413f-90da-361a2d7edebf"
    }'

If button Y is pressed, then the request issued will be:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
curl -X PUT \
  https://api.{region}.te2.io/rest/tracker/track \
    -H 'Authorization: Bearer {token}' \
    -H 'Content-Type: application/json' \
    -d '{
       "linkId": "1",                # link at index 1
       "eventType": "messageLinkTapped",
       "appId": "TE2Happyland_1.0",
       "messageId": "abc123",
       "action": "LinkTapped",
       "version": "1.0",
       "id": "7c63aa02-cd65-4f08-b9be-4fddd0545aee",
       "appUserId": "023b96ee-8aec-413f-90da-361a2d7edebf"
    }'