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