Tealium Collect HTTP API

Tealium Collect HTTP API

by on ‎01-09-2017 03:51 PM - edited on ‎05-15-2018 01:18 PM by Community Manager (6,719 Views)

This document describes how to send data to the Universal Data Hub using the HTTP API for events. This article provides the specification for the direct HTTP endpoint, which can be used in any application that can send HTTP requests.

In this article:

Table of Contents Placeholder 

Request Format

Tealium Collect is an HTTP endpoint that supports GET and POST methods.

Root URL

Tealium Collect is located at the following root URL: 

https://collect.tealiumiq.com/event

Standard Parameters

Tealium Collect supports the following standard parameters in each request:

  • tealium_account - the name of your Tealium account
  • tealium_profile - the name of your Tealium profile (default "main")
  • tealium_datasource - (optional) the data source key from UDH (learn more about Data Sources)
  • tealium_event - (recommended) the name of the event for tracking purposes
  • tealium_visitor_id - (required for AudienceStream) an anonymized and unique identifier for the visitor associated with the event (see Visitor Identifiers below)
  • tealium_trace_id - (optional) for use with Trace

The format of the request will vary depending on the HTTP method used. In the examples below placeholder values are represented with curly braces in the following format: {VALUE}.

Custom Event Parameters

Additional event attributes are sent as custom parameters according to your tracking needs. These parameters should also be defined as event attributes in the UDH.

Visitor Identifiers

If you are using AudienceStream you must pass a known visitor identifier attribute (secondary ID) with each tracking call (e.g. email_address or login_id). If the events do not contain a visitor identifier each event will generate a new visit and visitor and stitching will not be possible. This is especially important if using the Collect API on a web platform where you might be tracking anonymous users.

A visitor identifier is also needed if you are using EventStream and need to provide an ID to a vendor connector.

Learn more about what makes a good visitor identifier in the Visitor ID Attribute article.

Primary Visitor ID

The tealium_visitor_id attribute is an anonymous identifier used by AudienceStream to associate a visitor between events and visits.  Depending on your usage of the Collect API, you can use one of the following approaches:

  • Known Visitors (Recommended)
    When tracking events for a known visitor (when a value exists for a Visitor ID attribute such as email_address), include the known visitor ID attribute and a hash of that value in the tealium_visitor_id parameter.
    AudienceStream EventStream
    Required Recommended

    Example:
    {
        "tealium_account"    : "my_account",
      "tealium_profile" : "main",
    "tealium_event" : "user_login", "email_address" : "user@example.com",
    // MD5 Hash of user@example.com
    "tealium_visitor_id" : "b58996c504c5638798eb6b511e6f49af" }
  • Anonymous Visitors
    When tracking events for an anonymous visitor from a website (without a known identifier), then the value of the tealium_visitor_id will need to match the value in the utag_main_v_id cookie. (Learn more about the built-in variables from utag.js.)
    AudienceStream EventStream
    Required N/A

POST Method

The POST method supports JSON payloads where the request header must be set to Content-Type: application/json and the payload must be formatted as a valid JSON string. 

Let's use the following "user_login" event for our examples:

{
    "tealium_account"   : "{ACCOUNT}",
  "tealium_profile" : "{PROFILE}",
"tealium_event" : "user_login", "email_address" : "user@example.com" }

 

Example using curl:

curl -X POST -H 'Content-type: application/json' \
--data '{"tealium_account":"{ACCOUNT}","tealium_profile":"{PROFILE}","tealium_event":"user_login","email_address":"user@example.com"}' \
https://collect.tealiumiq.com/event

GET Method

The GET method passes data using key/value pairs in the query string of the endpoint. This method returns a 1x1 transparent GIF to make it compatible with HTML-based implementations.

Example using curl:

curl -i -X GET "https://collect.tealiumiq.com/event?tealium_account={ACCOUNT}&tealium_profile={PROFILE}&tealium_event=user_login&email_address=user@example.com" 

Usage Examples

HTML

Tealium Collect can be referenced in an <img> tag within your HTML. Due to browser caching it's important to include a cache buster, an additional parameter that contains a randomly generated value.

Example cache  buster:

var cb=Math.random()*100000000000;

This variable would be added to the query string of the Tealium Collect pixel:

<img height="1" width="1" style="display:none" src="//collect.tealiumiq.com/event?tealium_account={ACCOUNT}&tealium_profile={PROFILE}&tealium_event=user_login&email_address=user@example.com&cb=' + cb + '"/>

JavaScript

Tealium Collect supports cross-domain requests, so you can send a POST from your website to our domain. The Response Headers will include the following:  Access-Control-Allow-Origin: http://your_domain.com

var event = {
"tealium_account" : "{ACCOUNT}",
"tealium_profile" : "{PROFILE}",
"tealium_event" : "user_login",
"email_address" : "user@example.com"
};

var xhr = new XMLHttpRequest();
xhr.open("POST", "https://collect.tealiumiq.com/event");
xhr.send(JSON.stringify(event));