Articles in this section

See more

Event API

Avatar
Elizabeth
  • Updated
Follow

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.

  1. Debugging
  2. Pageload Event
  3. Identify Event
  4. Product View Event
  5. Add To Cart Event
  6. Remove From Cart Event
  7. Checkout Page Event
  8. Purchase Event
  9. Search Event
  10. Custom Events - Track any interaction
  11. Subscription Events
  12. Mobile Attributes
  13. Bulk Events
  14. 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 : 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

Related articles

Comments

0 comments

Please sign in to leave a comment.