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:
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.
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 :
scheme=a1webtag
to the base endpoint as a query-string parameter.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.application/json
.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:
events
JSON object in the API payload.customers
JSON object in the API payload.transactions
JSON object in the API payload.transactionitems
JSON object in the API
payload.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:
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.
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.
In the case where you should not send transactions
or transactionitems
objects (for reasons mentioned earlier):
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:
For more information on the status codes, see Status codes.
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.