This article assumes you are familiar with, and already successfully implemented, the webtag API authentication flow. If that’s not your case, please go back to Authentication for website & app implementations.
This API is leveraged by our Webtag SDK, hence the friendly name of “webtag API” used in other articles, but the rest of this article will refer to the “webtag API” by it’s technical endpoint name for precision, namely “tracker” API.
Before you start implementing those API calls, you should carefully review the data that you intend to pass to Customer Data Platform (CDP), and compare it to what other systems are already sending to us. As already mentioned in the article CDP entities, all data sources can send data about any entity to CDP, with no notion of “priority” between them. In short, anything you are sending with this API (or any other system for that matter), will overwrite what came before it for the related entity (if that entity existed prior to your API call) , and can be overwritten by any other system later on in the same way.
To re-iterate, the platform is very flexible in what data can be accepted (including consolidating sparse data from multiple sources), but it also means you have to be careful : you need to send data only from sources that you “trust”, and make sure you do not send overlapping data from other sources, lest you have no issues with that “source of truth” being overriden by other sources.
The tracker API is simply a way to pass data to our pipeline, and it maps/ exposes directly the entities that the CDP platform has configured for your tenant (both standard and configured ones). This article will not go through the description of those entities. If you need a refresher, you can read CDP entities to get familiar with the list of entities.
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 :
scheme=a1webtag
to the base endpoint described above, as a
query-string parameter.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.application/json
.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) :
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.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 :
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.
The calls below were written and executed against the CDP CS (aka “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 should be able to reproduce those calls “as is” once you replace with the proper parameters for your CDP tenant (e.g. replace the “a1cookie” value with a real cookie or unique visitor identifier like the mobile device ID, replace the “EmailAddress1” value with a real email address, etc…). If not, contact your CDP team.
Note that those 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 events below contain information about the device on which the event is triggered (mobile vs desktop, via the UserClient attribute on the events), which could be relevant and useful depending on your needs. Similar to a scaffolding/boilerplate code, they are here to illustrate the mechanism and the overall structure of some of the typical event calls you would make but do not constitute a reference for each and every case you might encounter. Please refer to the rest of the documentation as reference instead.
And, in the case where you should not send transactions/transactionitems objects (for reasons mentioned above):
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.