Tagging users

User tags are used to store data about users in the form of key-value pairs. These tags are used to store profile information, segment users, store some mobile application settings, and a variety of other purposes. This guide describes user tags and covers how to assign tags to a user, retrieve said tags, and remove tags.

Each user tag represents an attribute of information about the user that is recorded in order to collect data about the user or to mark users with classifications / segmentation information that have been determined externally to the accesso Guest Experience platform.

User tags can be used to hold various data, including but not limited to the following:

Data provided by the end users themselves, such as preferences or other demographic information that is voluntarily provided to make their interaction with accesso more personal.
Responses to surveys that the guest chooses to answer.
Data derived from external sources and correlated to accesso users.
Contextual information about the guest’s ticket purchasing activity (e.g., through accesso Ticketing) leading up to their visit to a venue.
Contextual information about the guest’s current experience, which is recorded when specific events are observed during their visit.

Because user tags are themselves entirely data-defined, you are free to define and change the set of user tags that you consider relevant, and can thus make accesso hold any applicable user profile information needed to serve experiences.

The values of user tags applicable to a user can be retrieved, set, changed, and deleted using the accesso Guest Experience platform’s REST APIs. Examples of how these APIs are used:

The guest mobile application can permit guests to directly enter information, which is then stored in the system as user tags.
accesso can set user tag values on a user in response to observed events derived from location data, such as the time of the user’s entry to a venue or the number of times that a user has been seen to enter a venue since they created their account.
accesso can set user tag values in response to events seen from other systems it has integrated with (for example, when the Guest Experience platform integrates with other accesso solutions to record information derived from observed ticket purchases or the use of virtual queuing solutions while in venues).

User tag definitions

User tags are themselves defined using user tag metadata, which stores the definition of the user tag: its name, its data type, etc.

User tags can be general or venue-specific:

General user tags: hold information pertaining to the user specifically, which does not vary by venue or have relevance with only specific venues.
Venue-specific user tags: can be applicable only in the context of specific venues or need to have a distinct/different value for each venue that the user visits. For example, a preference related to the user’s tolerance of “getting wet” might apply only for visits to venues with water rides or “splash zones” and would not be relevant at other venues.

Additionally, user tags can be permanent or transient:

Permanent user tags: pieces of information that remain relevant over time and never expire (for example, the user’s birthday or a stated preference that has general value).
Transient user tags: tags marked with an expiration time when the value of the tag is set, and accesso automatically “forgets” the recorded value when the expiration time arrives. Such tags can be used to record information that is relevant for a short time after the fact is noted, and loses value over time (for example, contextual facts about the user’s experience in the venue might lose value when the guest leaves the venue that day, and thus could be marked with a 24-hour expiry). By automatically forgetting tag values that have expired, accesso provides a way to avoid the risk of taking inappropriate action at a future date based on stale information.

User tags may be of any of the following data types:

Tag type	Definition
NUMBER	a numeric value (integer or real number)
TEXT	any arbitrary text string or value (e.g., user’s name)
SELECT	the tag must have one value from among a defined list of choices (e.g., what is your favorite superhero?)
MULTISELECT	the value of the tag is a collection of zero or more selections from among a defined list of choices (e.g., which of these foods do you enjoy?)
PHONE	the tag holds a phone number
EMAIL	the tag holds an email address

User tags can also be used to support segmentation or to hold general user profile data:

User segmentation: tags used to support segmentation must be of the enumeration or multi-enumeration data types (described below), so that they can be used with the Control Room application to define criteria (specific users) for which the experience is applicable.
General user profile data: tags used for holding general user profile data can be of any of the supported data types (listed below), but such tags cannot be directly used in Control Room to define criteria when creating experiences.

Tip: General user profile tags can be used to hold raw data and information of any type and from any source that could have statistical significance to the relevance of certain types of experiences. A common practice is to analyze such data and use it to arrive at stratified (enumerated) values, such as user segments or demographic segments. That derived information in turn can be imported as a separate (derived) user tag of an enumerated type, which can then be used to drive experiences. The distinction above is really intended to support this lifecycle.

In this way the product of advanced analytic techniques (like K-means clustering, logistic regression, etc.) can be applied to the raw data to arrive at a simpler set of classifications or segments. This simplified representation (enumerated user tags) can then be used freely from the Experience Management functions of Control Room without having to know the details of how those segments were derived from the raw data.

For example, the size of a travelling party might be known from ticket sales, and that party size (an integer) could be recorded on a user tag: ‘partySizeNextVisit’. Analysis might show that the party size can be stratified as: individuals (1), couples (2), small families (3-4), large families (5-6), and groups (7+). A separate select tag could be used to hold the derived group sizes, which could then be used as criteria for experiences created in Control Room.

Tags can have default values specified. If a given user does not have an explicit value for the tag recorded, then the tag APIs will return the default tag value when user tags are fetched for that user.

Tags also include additional display information such as the language-specific display name for the tags and for each of the values that apply to SELECT and MULTISELECT tag types, the image to use when displaying the tags as questions in surveys and on the mobile device, etc. These additional details can be seen in the tag definition APIs.

Tag definition APIs

The tags that are defined in the system can be seen using the /v1/tags/definitions API:

curl -X GET \
  https://api.{region}.te2.io/v1/tags/definitions \
  -H 'Accept: */*' \
  -H 'Accept-Language: en' \
  -H 'Content-Type: application/json' \
  -H 'Cache-Control: no-cache' \
  -H 'Authorization: Bearer {token}'

Sample response:

[
    /* Simple Text Tag to hold profile info (firstname) */
    {
        "missingTranslations": [],
        "customerId": "cf",
        "tagKey": "firstName",
        "title": "FirstName",
        "label": "First Name",
        "type": "TEXT",
        "supportsSegmentation": false,
        "userTagLevel": "CUSTOMER",
        "definitionType": "TAG",
        "values": []
    },
    /* Simple Text Tag to hold profile info (lastname) */
    {
        "missingTranslations": [],
        "customerId": "cf",
        "tagKey": "lastName",
        "title": "LastName",
        "label": "Last Name",
        "type": "TEXT",
        "supportsSegmentation": false,
        "userTagLevel": "CUSTOMER",
        "definitionType": "TAG",
        "values": []
    },
    /* Simple Select Tag to hold a true/false marketing opt-in option */
    {
        "missingTranslations": [],
        "customerId": "cf",
        "tagKey": "optInMarketing",
        "title": "OptInMarketing",
        "label": "Opt In Marketing",
        "type": "TEXT",
        "supportsSegmentation": true,
        "userTagLevel": "CUSTOMER",
        "definitionType": "TAG",
        "values": [
            {
                "missingTranslations": [],
                "label": "True",
                "imageUrl": "http://xx.com/image1",
                "displayOrder": 1,
                "tagValueKey": "true"
            },
            {
                "missingTranslations": [],
                "label": "False",
                "imageUrl": "http://xx.com/image2",
                "displayOrder": 2,
                "tagValueKey": "false"
            }
        ]

    },
    /* Multi-Select tag indicating the types of Rides the user likes,
       plus example of the use of images to support UIs that show the tags as icons */
    {
        "missingTranslations": [],
        "customerId": "cf",
        "tagKey": "Ride_Interests",
        "title": "Ride Interests",
        "label": "What types of rides are you most interested in?",
        "type": "MULTISELECT",
        "imageUrl": "http://foo.com/foo.jpeg",
        "supportsSegmentation": true,
        "userTagLevel": "CUSTOMER",
        "definitionType": "TAG",
        "values": [
            {
                "missingTranslations": [],
                "label": "Roller Coasters",
                "displayOrder": 1,
                "imageUrl": "http://xx.com/coaster",
                "tagValueKey": "Coasters"
            },
            {
                "missingTranslations": [],
                "label": "Thrill Rides",
                "displayOrder": 2,
                "imageUrl": "http://xx.com/thrill",
                "tagValueKey": "Thrill"
            },
            {
                "missingTranslations": [],
                "label": "Family Activities",
                "displayOrder": 3,
                "imageUrl": "http://xx.com/family",
                "tagValueKey": "Family"
            },
            {
                "missingTranslations": [],
                "label": "Kids Rides",
                "displayOrder": 4,
                "imageUrl": "http://xx.com/kids",
                "tagValueKey": "Kids"
            }
        ]
    },
    /* Venue-specific tag classifying the timeframe of the user's last visit */
    {
        "missingTranslations": [],
        "customerId": "cf",
        "tagKey": "lastVisitedDate",
        "title": "Last Visited",
        "label": "Last Visited",
        "imageUrl": "",
        "type": "TEXT",
        "defaultValue": "P0D",
        "supportsSegmentation": true,
        "userTagLevel": "VENUE",
        "definitionType": "TAG",
        "values": [
            {
                "missingTranslations": [],
                "label": "Today",
                "imageUrl": "",
                "displayOrder": 1,
                "tagValueKey": "P0D"
            },
            {
                "missingTranslations": [],
                "label": "Yesterday",
                "imageUrl": "",
                "displayOrder": 2,
                "tagValueKey": "P1D"
            },
            {
                "missingTranslations": [],
                "label": "1 Week Ago",
                "imageUrl": "",
                "displayOrder": 3,
                "tagValueKey": "P1W"
            },
            {
                "missingTranslations": [],
                "label": "2 Weeks Ago",
                "imageUrl": "",
                "displayOrder": 4,
                "tagValueKey": "P2W"
            },
            {
                "missingTranslations": [],
                "label": "3 Weeks Ago",
                "imageUrl": "",
                "displayOrder": 5,
                "tagValueKey": "P3W"
            },
            {
                "missingTranslations": [],
                "label": "1 Month Ago",
                "imageUrl": "",
                "displayOrder": 6,
                "tagValueKey": "P1M"
            },
            {
                "missingTranslations": [],
                "label": "2 Months Ago",
                "imageUrl": "",
                "displayOrder": 7,
                "tagValueKey": "P2M"
            },
            {
                "missingTranslations": [],
                "label": "3 Months Ago",
                "imageUrl": "",
                "displayOrder": 8,
                "tagValueKey": "P3M"
            },
            {
                "missingTranslations": [],
                "label": "6 Months Ago",
                "imageUrl": "",
                "displayOrder": 9,
                "tagValueKey": "P6M"
            }
        ]
    }
]

Variations of the above, which fetch only those tags that are applicable to a venue or are used only for segmentation, can be seen in the reference guide. They provide ways to filter the results to the tags of interest.

APIs also exist for defining new user tags and manipulating the values of user tags. These can be seen in the “Tags Definition Management” section of the User Tag Service API specification.
Consulting assistance regarding the use of these APIs is recommended, however.

Note: At the present time, accesso does not have a user-interface (e.g., screens within Control Room) that permits the definition and management of the user tags. APIs do exist for doing this, and accesso support services can assist in adding or modifying new tag definitions as needed.

Retrieving user tags

The current values of user tags can be retrieved using the following three tag service APIs:

API	Description
/v1/tags/users/uuid:{uuid}/tags	fetch all tags for the user (for both customer and venue-level)
/v1/tags/users/uuid:{uuid}/customers/tags	fetch all tags for the general level (i.e., not venue-specific)
/v1/tags/users/uuid:{uuid}/venues/{venue-id}/tags	fetch all tags for the user applicable to a specific venue

Or the following two identity service APIs:

API	Description
/v2/accounts/{accountId}/tags	fetch all tags for the user (for both customer and venue-level) by the user’s email address
/v3/accounts/{accountId}/tags	fetch all tags for the user (for both customer and venue-level) by the user’s email address

An example use of the /v1/tags/users/uuid:{uuid}/tags API, which fetches all current tag values, is as follows:

curl -X GET \
  https://api.{region}.te2.io/v1/tags/users/uuid:b21e0fc5-fbf3-11e9-87f8-fe5f62e2ce06/tags \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {token}'

Would produce a reply like:

[
    {
        "customerId": "cf",
        "tagMap": {
            "lastName": [
                {
                    "tagValue": "Walters",
                    "tagExpiration": "9999-11-11T12:00:00.000+0000",
                    "lastUpdated": "2019-10-31T15:32:50.063+0000"
                }
            ],
            "firstName": [
                {
                    "tagValue": "Bob",
                    "tagExpiration": "9999-11-11T12:00:00.000+0000",
                    "lastUpdated": "2019-10-31T15:32:50.066+0000"
                }
            ],
            "accountCreated": [
                {
                    "tagValue": "true",
                    "tagExpiration": "9999-11-11T12:00:00.000+0000",
                    "lastUpdated": "2019-10-31T15:32:50.149+0000"
                }
            ],
            "optInMarketing": [
                {
                    "tagValue": "true",
                    "tagExpiration": "2020-12-07T13:45:15.000+0000",
                    "lastUpdated": "2019-10-31T16:40:23.056+0000"
                }
            ],
            "firstTimeAppLogin": [
                {
                    "tagValue": "true",
                    "tagExpiration": "9999-11-11T12:00:00.000+0000",
                    "lastUpdated": "2019-10-31T15:32:50.199+0000"
                }
            ],
            "language": [
                {
                    "tagValue": "en",
                    "tagExpiration": "9999-11-11T12:00:00.000+0000",
                    "lastUpdated": "2019-10-31T15:32:50.068+0000"
                }
            ],
            "Ride_Interests": [
                {
                    "tagValue": "Coasters",
                    "tagExpiration": "2020-12-07T13:45:15.000+0000",
                    "lastUpdated": "2019-10-31T17:19:53.049+0000"
                },
                {
                    "tagValue": "Thrill",
                    "tagExpiration": "9999-11-11T12:00:00.000+0000",
                    "lastUpdated": "2019-10-31T17:19:53.047+0000"
                }
            ],
            "email": [
                {
                    "tagValue": "bob+1572535968956@theexperienceengine.com",
                    "tagExpiration": "9999-11-11T12:00:00.000+0000",
                    "lastUpdated": "2019-10-31T15:32:50.060+0000"
                }
            ]
        }
    },
    {
        "customerId": "cf",
        "venueId": "TE2_ORL",
        "tagMap": {
            "lastVisitedDate": [
                {
                    "tagValue": "P1W",
                    "tagExpiration": "2020-12-07T13:45:15.000+0000",
                    "lastUpdated": "2019-10-31T17:02:23.530+0000"
                }
            ]
        }
    }
]

Note that the tags are grouped in the general tags (an object with no venueId, but with an associated tagMap), and then into groupings by venue for those which apply to specific venues.

From the example above, the values of MULTISELECT tags (“Ride_Interests”) are returned as a JSON array of values, while the values of all other tags are returned as an array of a single value.

The other APIs work much the same and return the same reply structure and differ only in their URL paths and the filtering performed.

/v1/tags/users/uuid:{uuid}/customers/tags fetches all tags for the general level (i.e., all that are not venue-specific).
/v1/tags/users/uuid:{uuid}/venues/{venue-id}/tags fetches all tags for the user applicable to a specific venue. This includes all of the general tags, as well as tags associated with the specified venue. It does not include any tag values which are specifically associated with any other venues.

Manipulating user tag values of specific users

The /v1/tags/users/uuid:{uuid}/tags API can be used to set the value of a tag for any user based on that user’s UUID.

The identity service can also set tags for a user by accountId at the following endpoints:

API	Description
/v2/accounts/{accountId}/tags	Sets or deletes tags for the given user.
/v3/accounts/{accountId}/tags	Sets or deletes tags for the given user.

If setting a tag via the identity service endpoint, there is an optional parameter createAccountIfMissing. If createAccountIfMissing == true, a passwordless account will be created if a user does not exist for the supplied account ID.

This API requires a service token (i.e., authorization / confirmation that it is not originating from one of the guest mobile applications) as it is intended for use in systems integration.
(It cannot be used to permit one guest to set the tag values of another guest.)

An example POST call to set the values of some tags on a user (identified by the uuid path parameter) is as follows:

curl -X POST \
  https://api.{region}.te2.io/v1/tags/users/uuid:b21e0fc5-fbf3-11e9-87f8-fe5f62e2ce06/tags \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {token}' \
  -d '[
  {
    "tagKey": "firstName",
    "tagValue": "Bob"
  },
  {
    "tagKey": "optInMarketing",
    "tagValue": "true",
    "tagExpiration": "2020-12-07T13:45:15Z"
  },
  {
    "tagKey": "Ride_Interests",
    "tagValue": "Coasters",
    "tagExpiration": "2020-12-07T13:45:15Z"
  },
  {
    "tagKey": "Ride_Interests",
    "tagValue": "Thrill",
  },
  {
    "tagKey": "lastVisitedDate",
    "tagValue": "P1W",
    "venueId": "TE2_ORL",
    "tagExpiration": "2020-12-07T13:45:15Z"
  }
]'

On success, this API returns 204 with no body. If reaching this endpoint from the identity service, it will return a 200 with the UUID of the user.

The use of this API for MULTISELECT tag types uses a specific convention: The different values of the multi-select tag are simply passed as if setting the tab multiple times, as shown in the above example for the “Ride_Interests” tag. The value of that tag is set to the array of all the individual values specified. Each value can have an independent expiration time (as shown).

If the addMultiSelectValue=true parameter is provided when this API is called, the values given for MULTISELECT tags will be added to (not replace) the existing values already recorded for that tag. It permits a partial update of the current tag value via the addition of new values to the multi-select tag. For example, is a user currently had the value of only [ Coasters ] for the Ride_Interests tag, and a call was issued with addMultiSelectValue=true and one new value of Thrill, then upon completion, the value of the Ride_Interests tag for that user would be [ Coasters, Thrill ]. Without this parameter, the call would replace the existing value, setting the new value to [ Thrill ]

Removing tags from users

The previously described APIs for setting user tags can also be used to remove a tag from a user by specifying a tagValue of ‘null’ when the call is made, as in this example:

curl -X POST \
  https://api.{region}.te2.io/v1/tags/users/uuid:b21e0fc5-fbf3-11e9-87f8-fe5f62e2ce06/tags \
  -H 'Cache-Control: no-cache' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {token}' \
  -d '[
  {
    "tagKey": "optInMarketing",
    "tagValue": null
  }
]'

To remove values from a multi-select tag, the normal POST API should be used to pass in the complete, new set of values for the tag. There is no API convention that will remove specified values from an existing multi-select tag.

Setting and clearing user tags for the current user

The /v1/tags/users/me/tags API exists to permit a user to set the value of their own user tags, based on the security token that is acquired during authentication. The /v1/tags/users/me/tags REST API does not require (or permit) an explicit UUID value to be passed, and instead infers the correct UUID from the Authorization bearer token, which is passed to the API when it is called. This API can be used directly from guest-facing applications, based on the user’s own credentials.

An example of calling the /v1/tags/users/me/tags API follows.
The only difference from this and the explicit API described previously is the path convention of ‘me’.

curl -i -X POST \
  https://api.{region}.te2.io/v1/tags/users/me/tags \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer {token}' \
  -d '[
  {
    "tagKey": "firstName",
    "tagValue": "Bob"
  },
  {
    "tagKey": "optInMarketing",
    "tagValue": null,
    "tagExpiration": "2020-12-07T13:45:15Z"
  },
  {
    "tagKey": "lastVisitedDate",
    "tagValue": "P1W",
    "venueId": "TE2_ORL",
    "tagExpiration": "2020-12-07T13:45:15Z"
  }
]'

The format of the response is the same.