Using the webtag tracker API¶

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.

On-site search¶

Login¶

Category browsed¶

Product browsed¶

Cart update (1 product)¶

Cart update (multiple products)¶

Checkout¶

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

Status codes¶

After you make the API calls, the system displays a response status code to indicate the status of the API call. While there are multiple status codes, the following are the primary ones:

• 200: This status code indicates that the request succeeded.
• 401: This status code indicates that the client request is not complete because the request does not contain valid authentication credentials to access the server.
• 400: This status code indicates that the server cannot process the request because of a client error. For example, you get this code if you omit the access key from the call.

For more information on the status codes, see Status codes.