Blue Bite Tag Variable API

Table of Contents

Overview

The Blue Bite Tag Variable API is used to update information stored on an mTAG in Blue Bite's platform. A common use case for this feature is Product Registration, whereby a consumer fills out a form on the mobile experience, on successful form entry, the tag:variable is updated to indicate that the object is registered.

The class of mTAG properties are editable via this API is tag:variable. tag attributes and tag:data attributes cannot be edited via this API. This endpoint is open to anyone who can successfully interact with a Blue Bite object which can be done by scanning a QR code or tapping an NFC tag.

mTAG Configuration

In order to have a successful API response, these mTAG configurations must be made on the Dashboard:

  1. The mTAG must be assigned to the Experience Studio, or URL Redirect experience
  2. The mTAG tag:variable:<key> must exist on the mTAG. This API only grants permissions to update a key:value pair.

Studio Configuration

The studio supports this API natively via the Tag Variable action type.

Watch this space for more information on how to configure the Studio to update tag:variable

API Documentation

If you are updating tag:variable from a 3rd party client, you will need to do so via the Blue Bite Tag Variable API.

In order to successfully post to this API, the mTAG object needs to be configured properly (above) and you will need to extract the Interaction Rolling Key. The Rolling Key is a one-time key that will be used to authenticate that the client interacted with a Blue Bite object. The most common way to pass a rolling key to a 3rd party client is through a URL parameter with a Studio Macro.

Example: https://example.com?rk={{interaction:rk}}

Another method of extracting the Rolling Key can be found in our Rolling Key API documentation.

POST Blue Bite Tag Variable API (via REST client)

https://api.mtag.io/v2/interactions/data
{
  "rolling_key": "<Base64 encoded rolling key>",
  "data": {
    "<existing tag user data key>": "some value"
  }
}

Replace content nested within <> (including the brackets themselves) with what it references


Issued Rolling Keys have a Time To Live (TTL) of 5 minutes from interaction time.

Response

  • 200 OK {"success": true,"message": "User Data updated"}
  • 400 BAD REQUEST {"error": true,"message": "Invalid rolling key"}
    • Rolling Key is invalid
    • Rolling Key has been consumed
    • Rolling Key TTL has expired
    • tag:variable:<key> does not exist on the tag

Example

Flow
Redirect URL
https://example.com/nfc_page?rk=2y10XCZddmr0LYWazxYuW6OnAMS1SaCxrbywC4ucYwAWE8dV9nODrdSW

Base64 Encode
2y10XCZddmr0LYWazxYuW6OnAMS1SaCxrbywC4ucYwAWE8dV9nODrdSW → Base64 → MnkxMFhDWmRkbXIwTFlXYXp4WXVXNk9uQU1TMVNhQ3hyYnl3QzR1Y1l3QVdFOGRWOW5PRHJkU1c=

POST
https://api.mtag.io/v2/interactions/rk_payload?rk=MnkxMFhDWmRkbXIwTFlXYXp4WXVXNk9uQU1TMVNhQ3hyYnl3QzR1Y1l3QVdFOGRWOW5PRHJkU1c=

Example Request

Example Request - Valid
curl --request POST \
  --url 'https://api.mtag.io/v2/interactions/data'
  --header "Content-Type: application/json" \
  --data "{
    \"rolling_key\": "MnkxMFhDWmRkbXIwTFlXYXp4WXVXNk9uQU1TMVNhQ3hyYnl3QzR1Y1l3QVdFOGRWOW5PRHJkU1c=",
    \"data\": {
        \"<key_1>\": \"<value_1>\",
        \"<key_2>\": \"<value_2>\"
    }
}"