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. Therefore, see Authentication for website & app implementations to determine the subdomains that you use. This subdomain looks 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 for your CDP tenant is, /v2/999/dw/tracker. This is composed of the version - v2, tenant ID - 999, and 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 as a query-string parameter.
• Append accessKey=[yourKeyHere] to the URL as a query-string parameter. This key is the result of the steps described in Authentication for website & app implementations.
• Add the data you want to send to the tracker API in the body of the request, as a payload with content type set to application/json.
• Acquia recommends 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 entities as top level elements such as events. The “events” is a mandatory element. You can include other elements for specific events, but they are technically not necessary.

As a reference, CDP supports the following standard entities 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.
• You can enable other standard entities such as “Product”, “ProductCategory”, “Organization”. Before using these entities, ensure to review the use case with your CDP team.
• You can enable custom entities for updates through the webtags such as Wishlists and Reviews. Before using these entities, ensure to review the use case with your CDP team. The CDP team will configure it in the platform so that you can send events with these entities. The CDP team will provide you the actual JSON naming for these objects.

Depending on the actual type of event and other parameters, your payload looks like:

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

The top-level objects in the JSON payload can in turn contain a JSON list of JSON objects for that entity, allowing you to create or update multiple records for each entity with one call.

This API does not drive bulk data creation or updates. Acquia recommends that you always send atomic entity updates whenever events occur. Atomic entity updates typically cover only one customer, one event, one transaction and most likely less than 5-10 transaction items.

Acquia recommends that you send less than 10 objects for each entity. If you have a specific need for more objects per entity, contact your CDP team.

Each 2nd-level object in those lists now represents an instance of the top-level entity that you create or update with its attributes and values. The payload now looks like:

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

Some attributes are required for each entity, particularly when leveraging the API to create or update entities. Whereas, some attributes are optional. All will follow the requirements, naming and casing defined for the feeds:

• Event instances- See Event Feed. For mobile applications, pay attention to UserClient and DeviceType.
• Customer instances- See Customer Feed. For mobile applications, pay attention to MobileAdvertisingId and MobileDeviceId.
• Transaction instances- See Transaction Feed.
• TransactionItem instances- See Transaction Item Feed.

The following section explains the examples to tackle this situation in the pure API implementation.

On-site search¶

Login¶

Category browsed¶

Product browsed¶

Cart update (1 product)¶

Cart update (multiple products)¶

Checkout¶

In the case where you should not send transactions or transactionitems objects (for reasons mentioned earlier):

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.
• 500: This status code indicates an internal server error, error processing tracking data, and failure to send the payload to the message channel.

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