Information for: DEVELOPERS   PARTNERS   SUPPORT

Using the webtag tracker API

Prerequisite

Before using the webtag tracker API, ensure that you successfully implement the webtag API authentication flow. For more information, see Authentication for website & app implementations.

The Webtag SDK leverages this API. Therefore, the term webtag API is used in other sections. For precision, this section, uses the term tracker API.

Important

Before implementing API calls, you must carefully review the data that you intend to pass to CDP, and compare it with another system’s data that is already reaching to CDP. For more information, see CDP entities. All data sources can send data about any entity to CDP, without prioritizing the data sources. For an entity, any data that you send with this API or any other system overwrites the previously sent data if that entity existed prior to your API call.

The platform is very flexible in terms of acceptable data, including consolidating sparse data from multiple sources. However, it implies that you:

  • Send data only from trusted sources.
  • Ensure not to send overlapping data from other sources.

Entities & data model

The tracker API is a way to pass data to the CDP pipeline. It directly maps or exposes the entities that the CDP platform has configured for your tenant (both standard and configured ones). For more information, see CDP entities to get familiar with the list of entities.

Note

If a CDP attribute is defined as string type and there is no value defined for that attribute, either remove the attribute from the API call or send the value as null. Sending an empty string will cause an error.

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. 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.

Important

Send the Transactions and TransactionItem if the SourceTransactionNumber and SourceTransactionItemNumber values correspond to the standard Transaction feed and standard Transaction Item feed that you send to CDP. If the same transactions come through the webtag with different identifiers, the system creates a new transaction in CDP, which is the duplicate of an existing transaction. This results in doubling any revenue or transaction count, or other metrics. This is also true for the SDK implementation, see Examples of web event tracking.

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

Call examples

The calls in this example are written and executed against the CDP CS or 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 can reproduce those calls “as is” after replacing the parameters with the proper parameters for your CDP tenant. For example, replace the “a1cookie” value with a real cookie or unique visitor identifier like the mobile device ID and replace the “EmailAddress1” value with a real email address. For assistance, contact your CDP team.

Note

The 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 following events contains information about the device where the event is triggered. For example, mobile or desktop through the UserClient attribute on the events, which can be relevant and useful depending on your needs. Similar to a scaffolding or boilerplate code, the example illustrates the mechanism and the overall structure of some of the typical event calls you can make but do not constitute a reference for each and every case you might encounter.

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

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

appendix_3

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.

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.