Event API

You may use the event API to send events from your server-side, or use javascript events that will call the Blueshift API. You can find the Event API keys within the Blueshift dashboard.

Debugging
Pageload Event
Identify Event
Product View Event
Add To Cart Event
Remove From Cart Event
Checkout Page Event
Purchase Event
Search Event
Custom Events - Track any interaction
Subscription Events
Mobile Attributes
Bulk Events
Error Handling

Debugging

You may visit the page at https://app.getblueshift.com/dashboard#/app/click_stream/index to view the click-stream in real-time. The page shows a count of events received and a sample of the last event received of each type. You may use this to debug your integration, and ensure the right data is being sent to Blueshift.

cURL

curl -u <EVENT_API_KEY>: https://api.getblueshift.com/api/v1/event/debug

Alternatively, you can use the event debugging API end-point to help you in your development process. The event debugger returns the most recent events our server has seen of each type. You can use this API call to ensure the event attributes match our expectation in this document.

You can pipe the output through a tool that can improve readability (assuming you use python):

cURL

curl -u <EVENT_API_KEY>: https://api.getblueshift.com/api/v1/event/debug | python -m json.tool

Data Types

Blueshift accepts the following formats for Date, Boolean and Number data. It's very important to make sure your data is sent to Blueshift in these formats. Deviating from this format will mean the data will most likely just be stored as a string which will limit your ability to query the data in segmentation and limit your ability to format it when messaging your customers.

Data Type	Format	Correct Example	Incorrect Example
Date	ISO 8601	2016-04-12T17:27:20+00:00 2016-04-12T17:27:20Z 20160412T172720Z	11/11/2011
Boolean	lowercase string of `true` or `false`	true	TRUE
Number	must only contain numbers, no spaces or other characters	42	$42

How to format a your date as ISO8601 with Javascript

If your system does not use ISO8601compliant dates, you can format them before sending an event like so:


var yourDate = new Date('11/11/2011');
var yourDateInISO8601 = yourDate.toISOString(); // "2011-11-11T08:00:00.000Z"

To avoid parsing ambiguities and handle timezone use momentjs


var yourDate = '11/11/2011';
var yourDateInTimezone = moment.tz('11/11/2011','MM/DD/YYYY','America/New_York');
yourDateInTimezone.format(); // "2011-11-11T00:00:00-05:00"

Pageload

Fire this event on every page of your site. You can fire this before the close of your </head> tag. This event also serves as the loader for Blueshift's tracking pixel. Please replace the EVENT_API_KEY below with the event api key from Blueshift dashboard at https://app.getblueshift.com/dashboard#/account/api.

Parameters:

url
referrer
ip
customer_id
user_agent

JavaScript

<script type="text/javascript">
window._blueshiftid='<EVENT_API_KEY>';window.blueshift=window.blueshift||[];if(blueshift.constructor===Array){blueshift.load=function(){var d=function(a){return function(){blueshift.push([a].concat(Array.prototype.slice.call(arguments,0)))}},e=["identify","track","click","pageload","capture","retarget"];for(var f=0;f<e.length;f++)blueshift[e[f]]=d(e[f])};}
blueshift.load();
blueshift.pageload();
if(blueshift.constructor===Array){(function(){var b=document.createElement("script");b.type="text/javascript",b.async=!0,b.src=("https:"===document.location.protocol?"https:":"http:")+"//cdn.getblueshift.com/blueshift.js";var c=document.getElementsByTagName("script")[0];c.parentNode.insertBefore(b,c);})()}
</script>

Identify

Fire this event when you can identify the user that has logged in, or when you need to pass a user attribute for a known user. You must include a unique identifying parameter like customer_id or email or device_id.

JavaScript

<script>
  blueshift.identify({
   customer_id:'11111', // TODO: Replace with your customer identifier
   email: 'johndoe@somedomain.com', // TODO: Replace with your customer's email address
   joined_at: '2015-03-17T17:27:20+00:00', // TODO: Replace with your customer's join date
   firstname: 'John', // TODO: Replace with your customer's firstname (optional)
   lastname: 'Doe', // TODO: Replace with your customer's lastname (optional)
   other: 'value' // TODO: Optionally, add any user specific attributes from your CRM system (optional)
  });
</script>

device_id is the mobile specific (iOS or Android) device identifier to uniquely identify the mobile device.

cURL


curl -v -H "Accept: application/json" -H "Content-type: application/json" -X POST -d '
  {"customer_id":"812122",
   "event":"identify",
   "device_type": "ios",
   "device_tokens": "49244924492449244924492449244924492449244924",
   "device_id": "4444444",
   "device_idfa": "3333",
   "device_idfv": "33133",
   "device_manufacturer": "Apple",
   "os_name": "ios",
   "network_carrier": "verizon",
   "ip": "201.44.11.21",
   "email": "abc@def.com",
   "latitude": "212.99333",
   "longitude": "-12.39334"
  }' -u <EVENT_API_KEY>: https://api.getblueshift.com/api/v1/event

Product View

Fire this event when the user views a product page on your site/app.

JavaScript

<script type="text/javascript">
  blueshift.track("view", {
    products: [
       {
        sku: '45790-32'  // TODO: Replace with product id
       }
    ]});
</script>

cURL

curl -v -H "Accept: application/json" -H "Content-type: application/json" -X POST -d '
  {"customer_id":"812122",
   "event":"view",
   "products": [
        {
          "sku": "33133445-444"
        }
   ],
   "device_type": "ios",
   "device_tokens": "49244924492449244924492449244924492449244924",
   "device_id": "4444444",
   "device_idfa": "3333",
   "device_idfv": "33133",
   "device_manufacturer": "Apple",
   "os_name": "ios",
   "network_carrier": "verizon",
   "ip": "201.44.11.21",
   "email": "abc@def.com",
   "latitude": "212.99333",
   "longitude": "-12.39334"
  }' -u <EVENT_API_KEY>: https://api.getblueshift.com/api/v1/event

Add to Cart

Fire this event when the user adds an item to shopping cart.

JavaScript

<script type="text/javascript">
   blueshift.track("add_to_cart", {product_id: 'sku1'}); // TODO: Replace with value of product_id from your catalog
</script>

cURL

curl -v -H "Accept: application/json" -H "Content-type: application/json" -X POST -d '
  {"customer_id":"812122",
   "event":"add_to_cart",
   "products": [
        {
          "sku": "33133445-444"
        }
   ],
   "device_type": "ios",
   "device_tokens": "49244924492449244924492449244924492449244924",
   "device_id": "4444444",
   "device_idfa": "3333",
   "device_idfv": "33133",
   "device_manufacturer": "Apple",
   "os_name": "ios",
   "network_carrier": "verizon",
   "ip": "201.44.11.21",
   "email": "abc@def.com",
   "latitude": "212.99333",
   "longitude": "-12.39334"
  }' -u <EVENT_API_KEY>: https://api.getblueshift.com/api/v1/event

Remove From Cart

Similar to Add To Cart event above, you can also send us a Remove Cart (remove_from_cart) event whenever a user removes cart items.

Checkout Page

Fire this event when the user viewed the checkout page with all the order details before final purchase.

JavaScript

<script type="text/javascript">
    blueshift.track('checkout', {
      email: 'user@domain.com',  // TODO: Replace with your customer's email address
      total: 30,  // TODO: Replace with cart total
      products: [
       {
        sku: '45790-32'  // TODO: Replace with product id
       },
       {
        sku: '46493-33'
       }
     ]
    });
</script>

cURL

curl -v -H "Accept: application/json" -H "Content-type: application/json" -X POST -d '
  {"customer_id":"812122",
   "event":"checkout",
   "total": 6000,
   "products": [
        {
          "sku": "33133445-444"
        },
        {
          "sku": "33133445-445"
        }
   ],
   "device_type": "ios",
   "device_tokens": "49244924492449244924492449244924492449244924",
   "device_id": "4444444",
   "device_idfa": "3333",
   "device_idfv": "33133",
   "device_manufacturer": "Apple",
   "os_name": "ios",
   "network_carrier": "verizon",
   "ip": "201.44.11.21",
   "email": "abc@def.com",
   "latitude": "212.99333",
   "longitude": "-12.39334"
  }' -u <EVENT_API_KEY>: https://api.getblueshift.com/api/v1/event

Purchase

Fire this event when the user completes a purchase.

JavaScript

<script type="text/javascript">
    blueshift.track('purchase', {
      email: 'user@domain.com',  // TODO: Replace with your customer's email address
      order_id: '50314',  // TODO: Replace with order id
      total: 30,  // TODO: Replace with cart total
      revenue: 25,  // TODO: Replace with revenue
      shipping: 3,
      tax: 2,
      discount: 2.5,  // TODO: Replace with discount
      coupon: 'hasbros',  // TODO: Replace with coupon code
      products: [
       {
        sku: '45790-32',  // TODO: Replace with product id
        price: 19,  // TODO: Replace with price
        quantity: 1  // TODO: Replace with quantity
       },
       {
        sku: '46493-32',
        price: 3,
        quantity: 2
       }
     ]
    });
</script>

cURL

curl -v -H "Accept: application/json" -H "Content-type: application/json" -X POST -d '
  {"customer_id":"812122",
   "order_id": "4424553",
   "event":"purchase",
   "revenue": 5000,
   "products": [
        {
          "sku": "33133445-444",
          "price": 331.33
        },
        {
          "sku": "33133445-445",
          "price": 2331.33
        }
   ],
   "device_type": "ios",
   "device_tokens": "49244924492449244924492449244924492449244924",
   "device_id": "4444444",
   "device_idfa": "3333",
   "device_idfv": "33133",
   "device_manufacturer": "Apple",
   "os_name": "ios",
   "network_carrier": "verizon",
   "ip": "201.44.11.21",
   "email": "abc@def.com",
   "latitude": "212.99333",
   "longitude": "-12.39334"
  }' -u <EVENT_API_KEY>: https://api.getblueshift.com/api/v1/event

Search

Track user searches, and the products returned on the search results page. This pixel helps you create abandoned search campaigns.

JavaScript

blueshift.track("search", {
    keywords: 'Search Keyword', // TODO: Replace with value of keywords
    product_ids: [
      'SKU1', // TODO: Replace with value of a search result product_id
      'SKU2'
  ]
});

cURL

curl -v -H "Accept: application/json" -H "Content-type: application/json" -X POST -d '
{
"customer_id":"812122",
 "event": "search",
 "keywords": "pizza",
 "product_ids": [
   "84623739",
   "84623740",
   "84623741",
   "84623742",
   "84623743",
   "84623744",
   "84623745",
   "84623746",
   "84623753",
   "84623755"
 ],
} -u <EVENT_API_KEY>: https://api.getblueshift.com/api/v1/event

Custom Events (Track any interaction)

You can send custom events to Blueshift and use the event and attributes for segmentation.

JavaScript

<script type="text/javascript">
  blueshift.track("your_custom_event_name", {attribute1: 'value1', attribute2: 'value2'});
</script>

cURL

curl -v -H "Accept: application/json" -H "Content-type: application/json" -X POST -d '
  {"customer_id":"812122",
   "event":"your_custom_event_name",
   "attribute1": "value1",
   "attribute2": "value2"
  }' -u <EVENT_API_KEY>: https://api.getblueshift.com/api/v1/event

Subscription Events

Blueshift supports these subscription events to track subscription starts, stops, upgrades, downgrades, billing/collection and cancellation. You may use these events if you have a recurring subscription product.

Subscription Started

cURL

curl -v -H "Accept: application/json" -H "Content-type: application/json" -X POST -d '
  {"email":"someemail@domain.com",
   "event":"subscription_start",
   "subscription_period_type": "month",
   "subscription_period_length":"1",
   "subscription_plan_type": "subscription-sku-name1",
   "subscription_amount": "29.99",
   "subscription_started_at": "2015-03-17T17:27:20+00:00",
   "subscription_end_at": "2015-06-17T17:27:20+00:00"
  }' -u <EVENT_API_KEY>: https://api.getblueshift.com/api/v1/event

Subscription Upgraded

cURL


curl -v -H "Accept: application/json" -H "Content-type: application/json" -X POST -d '
  {"email":"someemail@domain.com",
   "event":"subscription_upgrade",
   "subscription_period_type": "month",
   "subscription_period_length":"1",
   "subscription_plan_type": "subscription-sku-name2",
   "subscription_amount": "39.99",
   "subscription_started_at": "2015-04-17T17:27:20+00:00"
  }' -u <EVENT_API_KEY>: https://api.getblueshift.com/api/v1/event

Subscription Downgraded

cURL

curl -v -H "Accept: application/json" -H "Content-type: application/json" -X POST -d '
  {"email":"someemail@domain.com",
   "event":"subscription_downgrade",
   "subscription_period_type": "month",
   "subscription_period_length":"1",
   "subscription_plan_type": "subscription-sku-name3",
   "subscription_amount": "9.99",
   "subscription_started_at": "2015-03-17T17:27:20+00:00"
  }' -u <EVENT_API_KEY>: https://api.getblueshift.com/api/v1/event

Subscription Billing

cURL

curl -v -H "Accept: application/json" -H "Content-type: application/json" -X POST -d '
  {"email":"someemail@domain.com",
   "event":"subscription_billing",
   "revenue": "19.99",
   "billing_date": "2014-14-11T17:27:20+00:00"
  }' -u <EVENT_API_KEY>: https://api.getblueshift.com/api/v1/event

Subscription Canceled

cURL


curl -v -H "Accept: application/json" -H "Content-type: application/json" -X POST -d '
  {"email":"someemail@domain.com",
   "event":"subscription_cancel",
   "subscription_plan_type": "subscription-sku-name",
   "subscription_canceled_at": "2016-04-12T17:27:20+00:00"
  }' -u <EVENT_API_KEY>: https://api.getblueshift.com/api/v1/event

Mobile Attributes

Attribute	Description
device_type	(apple / android / windows)
device_id	unique mobile device identifier, used to track user activity pre-sign up.
device_tokens	Push message device token (Required for push messaging)
device_idfa	iOS device identifier for advertiser
device_idfv	iOS device identifier for vendor
latitude	Location latitude
longitude	Location longitude
os_name	iOS etc.
os_version	OS version (eg. 6.1)
network_carrier	Carrier name (eg: Verizon)

Bulk Events

You may send events to Blueshift in bulk via your server-side integration. The bulk API call is network efficient by reducing the number of connections needed. The maximum size of a payload is 1MB or 100 events per payload. Multiple bulk events may be sent as part of an array. We recommend you to limit the no. of bulk calls to 5 per second ( 500 events/sec) Example:

cURL

curl -v -H "Accept: application/json" -H "Content-type: application/json" -X POST -d '
{"events":
 [
  {"customer_id":"812122",
   "event":"identify",
   "device_type": "ios",
   "device_tokens": "49244924492449244924492449244924492449244924",
   "device_id": "4444444",
   "device_idfa": "3333",
   "device_idfv": "33133",
   "device_manufacturer": "Apple",
   "os_name": "ios",
   "network_carrier": "verizon",
   "ip": "201.44.11.21",
   "email": "abc@def.com",
   "latitude": "212.99333",
   "longitude": "-12.39334"
  },
  {"customer_id":"812123",
   "event":"purchase",
   "ip": "201.44.11.22",
   "email": "abcd@def.com",
   "revenue": "31.24"
  }
 ]
} ' -u <EVENT_API_KEY>: https://api.getblueshift.com/api/v1/bulkevents

Error Handling

Code	Text	Description
400	Bad Request	The request was invalid or cannot be otherwise served. An accompanying error message will explain further
413	Payload Too Large	The server is refusing to process a request because the request payload is larger than the server is willing or able to process. Please reduce your pay load.
429	Rate limit exceeded	Too many requests, please contact blueshift for recommended throughput's.
500	Internal Server Error	Please contact blueshift for more information
502	Service unavailable, please retry	Bad Gateway, re-try with exponential backoff
503	Service unavailable, please retry	Service Unavailable, re-try with exponential backoff
504	Service unavailable, please retry	Gateway Timeout, please re-try with exponential backoff

Event API

How to format a your date as ISO8601 with Javascript

Comments