Tag Variable API

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

The class of editable object properties via this API is tag:variable. Tag attributes and custom tag data attributes cannot be edited via this API; they can only be edited when logged into the Blue Bite Platform. The tag variable 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 in the Dashboard:

  • The object must be assigned to an Experience in the Studio or to a URL Redirect experience
  • The object tag:variable:<key></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.

API Documentation

If you are updating tag:variable from a third party, 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 (see 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 physically interacted with a Blue Bite object. The most common way to pass a rolling key to a third party client is through a URL parameter with a 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_ROLLING_KEY>"
   "data": {
      "<KEY_1>": "<VAL_1>",
      "<KEY_2>": "<VAL_2>",
   }
}

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</key>

Example

Flow

Redirect URL
https://example.com/nfc_page?rk=2y10XCZddmr0LYWazxYuW6OnAMS​1SaCxrbywC4ucYwAWE8dV9nODrdSW

Base64 Encode
‍2y10XCZddmr0LYWazxYuW6OnAMS​1SaCxrbywC4ucYwAWE8dV9nODrdSW → Base64 → MnkxMFhDWmRkbXIwTFlXYXp4WXV​XNk9​uQU1TMVNhQ3hyYnl3QzR1Y1l3Q​VdFOGRWOW5PRHJkU1c=

POST
‍https://api.mtag.io/v2/interactions/rk_payload?rk=MnkxMFhDWmRkbXIwTFlXYXp4WXV​XNk9​uQU1TMVNhQ3hyYnl3QzR1Y1l3Q​VdFOGRWOW5PRHJkU1c=

Example Request

Example Request - Valid

curl --request POST \
 --url 'https://api.mtag.io/v2/interactions/data'
 --header "Content-Type: application/json" \
 --data "{
   \"rolling_key\": "MnkxMFhDWmRkbXIwTFlXYXp4WXV​XNk9​uQU1TMVNhQ3hyYnl3QzR1Y1l3Q​VdFOGRWOW5PRHJkU1c=",
   \"data\": {
       \"<key_1>\": \"<value_1>\",</value_1></key_1>
       \"<key_2>\": \"<value_2>\"</value_2></key_2>
   }
}"