Skip to main content

Event Collection

Kevel Audience enables you to collect real-time events in your customer data platform with first-party tags:

  • The preferred method for capturing events from your website is via JavaScript tag;
  • Alternative methods are provided for when JavaScript is not available for capturing events:

Via JavaScript Tag​

This method provides the most flexible approach for tracking events and it is the preferred method. Its main use case it to capture user interactions with the E-commerce website. The event channels expected to be collected via this method are: Web and E-Commerce.

Including the Tag​

In order to use the tag in a site, the following snippet is the minimum piece of code that should be included on the page. It should be added as close to the opening <head> tag as possible. This snippet only needs to be included once per page.

<script async src="https://cdn.cdp.<WEBSITE_DOMAIN>/pcdp_1.0.js"></script>

<script>
  window.pcdpLayer = window.pcdpLayer || [];
  window.pcdp = function(){pcdpLayer.push(arguments)};
</script>
Don't forget to change the URL

Since Kevel Audience provides a first-party system for each client, each client must include the system-tailored script tag from their domain. The URL should be replaced with your system endpoint. This applies to all interactions.

For standard installations, a client whose website is at example.com would use the following URL: https://cdn.cdp.example.com/pcdp_1.0.js.

For a detailed JavaScript tag API see JavaScript tag.

Using the Tag​

Once the tag as been included, you can begin collecting user interactions with your site by calling the pcdp function and specifying the required parameters for each event type.

<script>
  window.pcdpLayer = window.pcdpLayer || [];
  window.pcdp = function(){pcdpLayer.push(arguments)};

  pcdp("event", "track", {
    type: "pageView",
    ... // See required parameters for each event type
  })
</script>
info

For this example, you can see its required parameters in the Page View details page.

For more information about supported events and their details see the Complete list of events by categories.

Via Image (Pixel) Interface​

This interface does not require JavaScript and returns a 1x1px transparent gif image (pixel) which you can render anywhere on the page and track the user. It accepts the same parameters as the JavaScript tag, URL-encoded, as GET query parameters. Both HTTP and HTTPS are supported.

<img
  src="https://tr.cdp.<WEBSITE_DOMAIN>/events/pixel.gif?type=adView&clientId=<CLIENT_ID>&siteId=<SITE_ID>&campaignId=<CAMPAIGN_ID>&source=<SOURCE>"
  style="display: none; visibility: hidden; border: 0;"
  alt="" width="0" height="0" />
info

For this example, you can see its required parameters in the Ad View details page.

Via Click-Through Interface​

This interface is used to capture clicks before directing browsers to the original destination URL. It can be used for tracking clicks on display banners, search ads, e-mails, and any other type of click-through.

http://tr.cdp.<WEBSITE_DOMAIN>/events/click?type=adClick&clientId=<CLIENT_ID>&siteId=<SITE_ID>&<OTHER_PARAMETERS...>&ourl=<URL_ENCODED_DESTINATION_URL>

Please note that this interface requires you to URL-encode all parameters, including the ourl. For when it is not feasible to perform a URL encode on the ourl, you can use the next interface (/events/click0 instead of /events/click) where you can provide the non-encoded ourl but it must be the last query parameter of the URL.

http://tr.cdp.<WEBSITE_DOMAIN>/events/click0?type=adClick&clientId=<CLIENT_ID>&siteId=<SITE_ID>&<OTHER_PARAMETERS...>&ourl=<URL_NOT_ENCODED>
info

For these examples, you can see its required parameters in the Ad Click details page.

Via Server-Side Events​

The CDP provides an HTTP API to collect events from a server, as opposed to directly from your website or mobile applications. This API ignores client-related data in the HTTP request, such as the user IP, and provides an interface to specify user-related data, such as the User-Agent header, to avoid extracting wrong information from the request that relates to a server and not a user, and thus degrading user profiles.

For example, the IP is extracted from the HTTP headers in tracking events sent directly from your website, whereas in server-to-server events it is obtained via a parameter.
Additionally, the server-to-server API accepts an optional timestamp parameter, allowing you to specify the original timestamp of the event. For more details, please refer to the Event Tracker API.

Timestamp Restrictions
  • The event's timestamp maximum drift is 24 hours. Events that have occurred more than 24 hours ago will be rejected. The same applies for events whose timestamp is higher than their reception time in the server.
  • The timestamp must comply with the following ISO 8601 format: YYYY-MM-DD'T'hh:mm:ss[.sss]Z.
POST http://tr.cdp.<WEBSITE_DOMAIN>/events/server
Content-Type: application/json
{
  "type": "pageView",
  "siteId": <SITE_ID>,
  "clientId": <CLIENT_ID>,
  "user": {
    "type": <ID_TYPE>,
    "id": <ID>
  },
  "ip": <USER_IP>,
  "documentLocation": <DOCUMENT_LOCATION>,
  "timestamp": <TIMESTAMP>
}

API Reference​

For more technical details see the API Reference.

Event Verification​

Once you have tagged your website or during that process you can verify that the events are entering the system correctly using our dashboard.

Latest Collected Events in Dashboard​

You can see the latest collected events in the Dashboard under Collect > Events > All Events.

Dashboard latest events

Troubleshooting​

If all of your tags are implemented correctly, there is nothing more for you to do. However, in the case that something goes awry, you'll see an error message in the Events page of your Kevel Audience user interface, letting you know immediately what needs to be corrected.

Dashboard latest events error

Any time you see an yellow exclamation point in the ‘Event type' column, you can click into the event details to see the specific errors flagged for that event. When you see errors in your events stream, contact your Customer Success Manager and we will help resolve the issue.

Handling Bot Traffic​

Bots are software applications that have been programmed to automatically do certain (often repetitive) tasks without human user intervention. They can be of several different types, such as chatbots, social bots, web crawlers or malicious bots.

Hence, bot traffic is any non-human traffic happening in a website or application. While some of it is actually interesting and used by helpful services (eg. search engines, digital assistants), depending on the context of your website/app, this traffic may be something that you should not take into consideration as website/app activity.

Detecting Traffic​

Usually this type of traffic is detected by analysing the user-agent strings that are sent in the header of the HTTP request. This string provides information on where the request originated from, including the operating system, and browser.

Bots with no harmful intent often identify themselves with their own user-agent. Google, for example, made public the list of their user-agents and strings, with adjoining info on what they are used for.

Kevel Audience uses a library to maintain the list of user-agents identified as bots and filter the traffic from these.

This traffic is diverted and written in a different database, for short period of time, so that it can be used to debug any related issues, if needed.

If you are integrating with us directly, be aware that most non-browser traffic may be filtered. This applies to development tools (e.g. curl and wget) and others. Consider sending a whitelisted user-agent to prevent this.

Last updated on