Your site/app's event data

This article provides information on how to track your site or app's event data and send it to our platform.

Our platform provides API endpoints that you can use to send events from your site or app to our platform. Here are the API endpoints that you can use to send events from your site to our platform:

👍

Tip

The headings are linked to a page that provides options to try out the API.

You can use this endpoint to send an event from your site or app to our platform. An event could be: pageload, identify a customer, product view, add to cart, remove from cart, checkout, purchase, search, or a custom event on your site or app. You can use the JavaScript SDK that call the Blueshift APIs to send event data from your site to our platform. Here's how to send these events to our platform:

Pageload

Trigger this event before a page of your site loads to:

  • Track a visit to a page
  • Load Blueshift's tracking pixel

Ensure that you trigger this event for each page of your site and you can trigger it before the close of the </head> tag of a page. Replace the EVENT_API_KEY with the event API key that you generate from Blueshift dashboard. Here are the parameters for this event:

  • 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

Trigger this event when you can identify if the customer has logged in, or when you need to pass a user attribute for a known customer. You must include a unique identifying parameter like customer_id or email or device_id. You can pass additional attributes of the customer that you can use for personalization when you create a campaign.

<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>

Product view

Trigger this event when a user sees a product page on your site or app.

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

Add to cart

Trigger this event when a customer adds a product to cart. You can use this event to win back customers who add a product to a cart but abandon it later.

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

Remove from cart

Trigger this event when a customer removes a product from cart.

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

Checkout page

Trigger this event when a customer sees the checkout page and reviews the order before a purchase. You can use this event to run a campaign for customer who abandon a check out.

<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>

Purchase

Trigger this event when a customer completes a purchase on your site or app. You can use this event to:

  • Measure the performance of your campaign
  • Model recommendations to exclude some of the items that a customer has already ordered
  • Calculate customer affinities
<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>

Search

Trigger this event when a customer searches for something on your site or app. You can use this event to let us record customer interest.

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'
  ]
});

Custom event

Trigger this event to track any custom action that a customer performs on your site or app.

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

If you have a subscription based product where customers pay for your product on a recurring basis, you can use these events to track customer actions related to product subscriptions. Our platform can track subscription starts, stops, upgrades, downgrades, billing/collection, and cancellation.

Subscription started

Trigger this event when a customer starts a subscription.

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",
   "subscription_end_at": "2015-06-17T17:27:20+00:00"
  }' -u <EVENT_API_KEY>: https://api.getblueshift.com/api/v1/event

Subscription upgraded

Trigger this event when a customer upgrades a subscription.

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

Trigger this event when a customer downgrades a subscription.

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

Trigger this event when a customer pays a subscription fee.

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 cancelled

Trigger this event when a customer cancels a subscription.

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

You can send events to our platform in bulk from your server-side integration. The bulk API call reduces the number of connections needed so that it is network efficient. 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 that you limit the number of bulk calls to 5 per second (500 events/second). For 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

You can use this endpoint to debug your integration, and ensure the right data is being sent to Blueshift. You can visit the page using this link 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.

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. For example:

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

Updated 4 months ago


Your site/app's event data


This article provides information on how to track your site or app's event data and send it to our platform.

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.