Acquia CDP

Using the webtag tracker API

Prerequisite

Before using this API, you must successfully implement the WebTag API authentication flow. For more information, see Authentication for website and 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 and 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). For more information, see CDP entities to get familiar with the list of entities.

Note

If a CDP attribute is defined as a 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. If you send an empty string, CDP throws 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 must contain:

  • The base URL https://<environmentSubdomain>.agilone.com/. Subdomains differ per environment. Therefore, see Authentication for website and 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, which 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 and 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.

  • Ensure that you send requests only over HTTPS and not over HTTP.

  • Ensure that the API client sends the user-agent in the header. You do not need to assign a value for user-agent if it is checked.

DW tracker v3 (Limited Availability)

CDP provides the robust and secure DW tracker v3 to help you configure permissions up to the attribute level. This version is currently in Limited Availability for a select number of CDP customers. For those customers:

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

  • The tracker endpoint for your CDP tenant is /v3/999/dw/tracker, which is composed of the version - v3, tenant ID - 999, and dw/tracker endpoint for this API.

If you encounter any issue, switch to the v2 version of the API. If the issue persists, contact Contact Acquia Support.

Payload

Every payload you want to send to this API must be a well formatted JSON object, containing a collection of entities as top level elements such as events. The event is a mandatory element. You can include other elements for specific events.

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 configures it in the platform so that you can send events with these entities. The CDP team provides you the actual JSON naming for these objects.

  • EventTimeStamp must be sent as an epoch timestamp in milliseconds. To convert human-readable dates to epoch timestamp in milliseconds, use Epoch Converter.

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 second-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 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 the attributes 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 instance, replace the a1cookie value with an actual cookie or unique visitor identifier such as Source Customer Number or UUID, or the mobile device ID. Replace the EmailAddress1 value with a real email address. For assistance, contact your CDP team.

Note

The events and their associated images do not necessarily contain all the data that you can 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

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 a generic server error. Acquia recommends you to retry pushing the data.

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

Appendix

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