Register user devices

Device registration is the first step to make a user endpoint recognized in the accesso Guest Experience platform. It is a prerequisite for messaging, device location, user tagging, and other user flows. Mobile applications are the most common type of user device, but this flow can also be applied to responsive web sites, wearable devices, chatbots, and other user-facing endpoints.

Simple example

The following is a minimal “Hello World” example to register a new user device on the platform:

1
2
3
4
5
6
7
8
9
10
curl -i -X POST \
  https://api.{region}.te2.io/rest/user/device \
    -H 'Authorization: Bearer {token}' \
    -H 'Content-Type: application/json' \
    -d '{
            "appUserId": "{appUserId}",
            "appId": "{appId}",
            "userId": "{userId}",
            "platform": "{platform}"
        }'

This simple example will report the existence of a device with appUserId of {appUserId} to the platform with no other information.

A successful call will return 204 - No Content.

This example uses the following inputs:

• token: JWT token returned during authentication.
• 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.
• 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.
• userId: The ID of the user.
  Omitting the userId field will create a new user in the system. If the user has already been created, the userId field should be provided to establish an association between the existing user and the device.
• platform: The platform of the device being registered. Allowed values are: ANDROID, IOS, WEARABLE, and UNKNOWN.

Now the platform knows that the device exists, but nothing else.

To enable more interesting interactions we will need to provide more data. For example, you can report location information (refer to the Location tracking guide).

Registering for push notifications

Many user devices support out-of-band notifications. For mobile devices, these take the form of Apple and Google push notifications.

Apps and browsers need to request the user’s permission before they can send these notifications. Once the user accepts, the app will get a pushDeviceToken.

To enable push notifications through accesso, we need to report this pushDeviceToken to the platform:

1
2
3
4
5
6
7
8
9
10
11
curl -i -X POST \
  https://api.{region}.te2.io/rest/user/device \
    -H 'Authorization: Bearer {token}' \
    -H 'Content-Type: application/json' \
    -d '{
            "appUserId": "{appUserId}",
            "appId": "{appId}",
            "userId": "{userId}",
            "platform": "{platform}",
            "pushDeviceToken": "{pushDeviceToken}"
        }'

Where:

• platform: The device platform. This attribute tells accesso how to route push notifications to this device. For mobile apps, this will be IOS or ANDROID.