Information for: DEVELOPERS   PARTNERS

Using the webtag tracker API

Prerequisite

This article assumes you are familiar with, and already successfully implemented, the webtag API authentication flow. If that’s not your case, please go back to Authentication for website & app implementations.

This API is leveraged by our Webtag SDK, hence the friendly name of “webtag API” used in other articles, but the rest of this article will refer to the “webtag API” by it’s technical endpoint name for precision, namely “tracker” API.

Warning

Before you start implementing those API calls, you should carefully review the data that you intend to pass to Customer Data Platform (CDP), and compare it to what other systems are already sending to us. As already mentioned in the article CDP entities, all data sources can send data about any entity to CDP, with no notion of “priority” between them. In short, anything you are sending with this API (or any other system for that matter), will overwrite what came before it for the related entity (if that entity existed prior to your API call) , and can be overwritten by any other system later on in the same way.

To re-iterate, the platform is very flexible in what data can be accepted (including consolidating sparse data from multiple sources), but it also means you have to be careful : you need to send data only from sources that you “trust”, and make sure you do not send overlapping data from other sources, lest you have no issues with that “source of truth” being overriden by other sources.

Entities & data model

The tracker API is simply a way to pass data to our pipeline, and it maps/ exposes directly the entities that the CDP platform has configured for your tenant (both standard and configured ones). This article will not go through the description of those entities. If you need a refresher, you can read CDP entities to get familiar with the list of entities.

Endpoint and Payloads

Endpoint

A request URL looks like this: https://api6.agilone.com/v2/7/dw/tracker?scheme=a1webtag&accessKey=$2a$10$UZznrmUuKzT6FbmR1mADP.rscVdx.uM/S.0keoOaZ8oM68GXWzYKm. It always needs to contain:

  • The base URL https://<environmentSubdomain>.agilone.com/. Subdomains differ per environment, so please refer to Authentication for website & app implementations to determine which subdomain you should be using. This subdomain will look like:

    Environment Pre-Production Production
    US AWS cs-api6 api6
    EU AWS cs-api6.eu api6.eu
    US GCP cs-gcp-api6 api8
  • The tracker endpoint itself, for your CDP tenant : /v2/999/dw/tracker. This is in turn composed of the version (e.g. v2) , your tenant ID (e.g. 999) and the dw/tracker endpoint for this API.

All requests to this API are composed with the following rules :

  • Use only the POST method.
  • Append scheme=a1webtag to the base endpoint described above, as a query-string parameter.
  • Append accessKey=[yourKeyHere] to the URL as a query-string parameter. As a reminder, this key is the result obtained via the steps described in Authentication for website & app implementations.
  • The data you want to send to the tracker API should be contained in the body of the request, as a payload with content type set to application/json.
  • It is highly recommended that you send requests only over HTTPS, not HTTP.

Payload

Every payload you want to send to this API should be a well formatted JSON object, containing a collection of entites as top level elements (e.g. “events”). The “events” elements is always required, otherwise the API will return an error (this API is designed to track events, after all). Other elements can be included whenever needed for specific events, but are typically not necessary from a technical standpoint.

As a reference, the following standard entities are supported (with their mapping to the JSON payload naming convention) :

  • Event : maps to the “events” JSON object in the API payload.
  • Customer : maps to the “customers” JSON object in the API payload.
  • Transaction : maps to the “transactions” JSON object in the API payload.
  • TransactionItem : maps to the “transactionitems” JSON object in the API payload.
  • Other standard entities like “Product”, “ProductCategory”, “Organization”, etc… can be made accessible but should not be used without reviewing the use case with your CDP team first.
  • Custom entities can also be made accessible for updates via the webtag when it makes sense (e.g. Wishlists, Reviews, etc…). Please review the use case with your CDP team first, as they need to ensure it is properly configured in the platform before you send events with those entities. They will provide you with the actual JSON naming for those objects.

At this point, your payload should look something like this (its content will obviously depend on the actual type of event that you are sending, etc…) :

{
    "events":
        [{
            ...
        }],
    "customers":
        [{
                    ...
                }],
        ...
}

Those top-level objects in the JSON payload can in turn contain a JSON list of JSON objects for that entity, allowing you to create/update multiple records for each entity with one call. Be careful though, this API was not designed to drive bulk data creation/update, and we suggest that you always send atomic entity updates whenever events happen (which typically cover only 1 customer, 1 event, 1 transaction and most likely less than 5-10 transaction items). In any case, we strongly recommend that you never send more than 10 objects for each entity (contact your CDP team if you have a specific need for more objects per entity, there are probably more efficient and reliable ways to solve that use case).

Each of those 2nd-level objects in those lists now represent an instance of the top-level entity that needs to be created/updated, with its attributes and their value. The payload will now look like this :

{
    "events":
        [{
            "Cookie": "...",
            "Type": "...",
            "SourceCustomerNumber": "...",
            ...
        }],
    "customers":
        [{
                        "SourceCustomerNumber": "...",
                        "FirstName": "...",
                        ...
                }],
        ...
}

Some attributes are required for each entity (in particular when leveraging the API to create/update entities), some are optional. All will follow the requirements, naming and casing defined for the feeds :

  • Event instances : please refer to the article Event feed. In particular, for mobile applications it is interesting to pay special attention to UserClient and DeviceType mentioned there.
  • Customer instances : please refer to the article Customer feed. In particular, for mobile applications it is interesting to pay special attention to MobileAdvertisingId and MobileDeviceId mentioned there.
  • Transaction instances : please refer to the article Transaction feed
  • TransactionItem instances : please refer to the article Transaction Item feed

Important note on sending Transactions and TransactionItem entities : only send those if the SourceTransactionNumber and SourceTransactionItemNumber values correspond to what you are sending to CDP in the standard Transaction feed and standard Transaction Item feed. Otherwise, if the same transactions come via the webtag with different identifiers, it will create a new transaction in CDP that will be an exact duplicate of another transaction, thus doubling any revenue/transaction count/ other metrics. This is also true for the SDK implementation (see Examples of web event tracking). You can read below for the suggested way to tackle this situations in the pure API implementation.

Call examples

The calls below were written and executed against the CDP CS (aka “development”) environment API endpoint, with a dummy tenant and dummy data (tenant ID = 999 with the associated tokens and keys necessary to make this work). You should be able to reproduce those calls “as is” once you replace with the proper parameters for your CDP tenant (e.g. replace the “a1cookie” value with a real cookie or unique visitor identifier like the mobile device ID, replace the “EmailAddress1” value with a real email address, etc…). If not, contact your CDP team.

Note that those events and their associated screenshots do not necessarily contain all the data you should transmit to CDP for your use cases.For instance, none of the events below contain information about the device on which the event is triggered (mobile vs desktop, via the UserClient attribute on the events), which could be relevant and useful depending on your needs. Similar to a scaffolding/boilerplate code, they are here to illustrate the mechanism and the overall structure of some of the typical event calls you would make but do not constitute a reference for each and every case you might encounter. Please refer to the rest of the documentation as reference instead.

Login

Login event

Category browsed

CategoryBrowsed event

Product browsed

ProductBrowsed event

Cart update (1 product)

CartUpdated event

Cart update (multiple products)

CartUpdated multi products

Checkout

Checkout event

And, in the case where you should not send transactions/transactionitems objects (for reasons mentioned above):

appendix_3

Appendix

All examples above are obtained using Postman, a REST API client, or cURL, a command line instruction. You can obviously use any client, any library you like to test out and implement those calls in your environments.