DocumentationDeveloper PortalAPI EndpointsProduct Updates
Developer Portal
Contact Us

Event API & Javascript events

You may use the event API to send click-stream events from your server-side, or use javascript events that will hit the Blueshift API. You will need an event-stream API key which is accessible from Blueshift dashboard at https://app.getblueshift.com/dashboard#/account_setup or contact [email protected]

  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

Debugging

You may visit the page at http://app.getblueshift.com/dashboard#/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 -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 -u <EVENT_API_KEY>: https://api.getblueshift.com/api/v1/event/debug | python -m json.tool

Data Types

Blueshift's backend data stores are noSQL backed and can store JSON documents. The basic data types are Date, Boolean and Number data. In addition, you can include JSON hashes and arrays. 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 TypeFormatCorrect ExampleIncorrect Example
DateISO 8601

2016-04-12T17:27:20+00:00

2016-04-12T17:27:20Z

20160412T172720Z

11/11/2011
Booleanlowercase string of true or falsetrueTRUE
Numbermust only contain numbers, no spaces or other characters42$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
<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.

<script>
  blueshift.identify({
   customer_id:'11111', // TODO: Replace with your customer identifier
   email: '[email protected]', // 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 -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": "[email protected]",
   "latitude": "212.99333",
   "longitude": "-12.39334"
  }' -u <EVENT_API_KEY>: https://api.getblueshift.com/api/v1/event

Product View

Your app can fire this event when the user views a product page on your site/app.

<script type="text/javascript">
  blueshift.track("view", {
    products: [
       {
        sku: '45790-32'  // TODO: Replace with product id
       }
    ]});
</script>
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": "[email protected]",
   "latitude": "212.99333",
   "longitude": "-12.39334"
  }' -u <EVENT_API_KEY>: https://api.getblueshift.com/api/v1/event

Add to Cart

Your app can fire this event when the user adds an item to shopping cart.

<script type="text/javascript">
   blueshift.track("add_to_cart", {product_id: 'sku1'}); // TODO: Replace with value of product_id from your catalog
</script>
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": "[email protected]",
   "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

The app can fire this event when the user viewed the checkout page with all the order details before final purchase.

<script type="text/javascript">
    blueshift.track('checkout', {
      email: '[email protected]',  // 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 -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": "[email protected]",
   "latitude": "212.99333",
   "longitude": "-12.39334"
  }' -u <EVENT_API_KEY>: https://api.getblueshift.com/api/v1/event

Purchase

The app can fire this event when the user completes a purchase.

<script type="text/javascript">
    blueshift.track('purchase', {
      email: '[email protected]',  // 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 -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": "[email protected]",
   "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.

<script type="text/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'
            ]
          });
        </script>
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)

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

<script type="text/javascript">
  blueshift.track("your_custom_event_name", {attribute1: 'value1', attribute2: 'value2'});
</script>
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 -v -H "Accept: application/json" -H "Content-type: application/json" -X POST -d '
  {"email":"[email protected]",
   "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"
  }' -u <EVENT_API_KEY>: https://api.getblueshift.com/api/v1/event

Subscription Upgraded

curl -v -H "Accept: application/json" -H "Content-type: application/json" -X POST -d '
  {"email":"[email protected]",
   "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 -v -H "Accept: application/json" -H "Content-type: application/json" -X POST -d '
  {"email":"[email protected]",
   "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 -v -H "Accept: application/json" -H "Content-type: application/json" -X POST -d '
  {"email":"[email protected]",
   "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 -v -H "Accept: application/json" -H "Content-type: application/json" -X POST -d '
  {"email":"[email protected]",
   "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

AttributeDescription
device_type(apple / android / windows)
device_idunique mobile device identifier, used to track user activity pre-sign up.
device_tokensPush message device token (Required for push messaging)
device_idfaiOS device identifier for advertiser
device_idfviOS device identifier for vendor
latitudeLocation latitude
longitudeLocation longitude
os_nameiOS etc.
os_versionOS version (eg. 6.1)
network_carrierCarrier 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. Multiple bulk events may be sent as part of an array. Example:

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": "[email protected]",
   "latitude": "212.99333",
   "longitude": "-12.39334"
  },
  {"customer_id":"812123",
   "event":"purchase",
   "ip": "201.44.11.22",
   "email": "[email protected]",
   "revenue": "31.24"
  }
 ]
} ' -u <EVENT_API_KEY>: https://api.getblueshift.com/api/v1/bulkevents

Updated about 1 year ago

Did this page help you?