If you’re using an ecommerce platform not currently supported by one of Spur's existing partner integrations, or you’ve built your own custom solution, you can integrate with Spur using our APIs.
About JavaScript and server-side event APIs
Use our JavaScript API to track customer actions during a browsing session:
Product Viewed
When someone clicks on a product or a page on your website
Started Checkout
When someone lands on the checkout page.
Use our server-side API for events that happen on the backend, starting with when a customer places an order:
Placed Order
When an order successfully processes on your system.
Cancelled Product
When an order is cancelled.
JavaScript Track API for onsite metrics
Integrate Spur Scripts on your website
To be able to track events happening on your site, add the following Javascript snipped so it appears on every page on your website.
Make sure to replace the YOUR_WORKSPACE_ID with your Spur's workspace id which will be available to you on Spur Settings > API page.
<script
src="https://r2.spurnow.com/custom-spur-pixel.js?workspaceId=YOUR_WORKSPACE_ID"
async>
</script>
Once you’ve added the snippet above, an Active on Site metric can be triggered for any person who is cookied.
API basics
To make calls to the Spur APIs and store information about people, you'll use the spurPixel object that's automatically added to the window object by the custom-spur-pixel.js script.
Identifying people
The identifyUser method in spurPixel allows you to identify and set properties on an individual.
Example
<script>
// Example Function to identify a user and set cookies
// The phone parameter will be the phone number of the current user
function identify(phone) {
window.spurPixel.identifyUser(phone);
}
// The phone number must have the country code along with it
// Eg. identify("919888888888") or identify("+91 9888888888")
</script>
Example Response
{
"spcid" : SPUR_CONTACT_ID
}
Track events and actions
The trackEvent method allows you to record events and actions people take on your website. This method accepts a string which will be one of the Event Type and a payload object of properties associated with that event.
Event Types
product_viewedWhen someone clicks on a product or a page on your website
Example
window.spurPixel.trackEvent("product_viewed", {
productId: "1234",
productName: "Mens Bracelet",
price: 19.99,
imageUrl:
"https://exampleimage.com/url",
productUrl: "https://example.com",
});
checkout_startedWhen a checkout process starts on your website
Example
window.spurPixel.trackEvent("checkout_started", {
lineItems: [
{
productId: "prod001",
productName: "Awesome Widget",
price: {
amount: 299.99,
currency: "USD",
},
imageUrl: "http://example.com/product_image.jpg",
productUrl: "http://example.com/product",
},
],
value: 299.99,
totalPrice: {
amount: 299.99,
currencyCode: "USD",
},
checkoutUrl: "http://example.com/checkout",
billingAddress: {
firstName: "John",
lastName: "Doe",
address1: "123 Elm Street",
city: "Anytown",
country: "USA",
zip: "12345",
phone: "123-456-7890",
email: "[email protected]",
},
shippingAddress: {
firstName: "John",
lastName: "Doe",
address1: "123 Elm Street",
city: "Anytown",
country: "USA",
zip: "12345",
},
contactInfo: {
email: "[email protected]",
phone: "+91234567890",
},
});
The best place to trigger checkout_started event is either:
When someone visits the checkout page after they’ve been identified.
When they enter their email address on the checkout page if they have not already been identified.
Tracking server-side events
We separated tracking order related events on the server-side due to potential limitations of frontend code, security concerns, and general availability of data on the server-side versus the front-end.
Triggering Events
API Endpoint - https://api.spurnow.com/pixel/customServerEvent
To trigger a server side event, you need to make a POST request to the our API endpoint:
The
Authorizationheader of the request must set asbearer <YOUR_API_KEY>. Where<YOUR_API_KEY>must be replaced with your Spur API key. To create an API key on Spur, check out this article.The request must have a JSON body having the following properties
time- UTC string representation of the time the event was triggeredeventName- the name of the event eg.order_placedpayload- the event specific payload
Order Placed Event
After an order is placed at your backend, make a POST request to our customServerEvent API to create an order_placed event. Send the data in the payload as shown in the example request.
curl --location 'https://api.spurnow.com/pixel/customServerEvent'
--header 'Authorization: bearer YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '
{
"time": "2024-01-27T12:00:00.000Z",
"eventName": "order_placed",
"payload": {
"uniqueOrderId": "r2dzrvgyii8cswwfkbuak",
"value": 299.99,
"lineItems": [
{
"productId": "prod001",
"productName": "Awesome Widget",
"price": {
"amount": 299.99,
"currency": "USD"
},
"imageUrl": "http://example.com/product_image.jpg",
"productUrl": "http://example.com/product"
}
],
"currency": "INR",
"totalPrice": {
"amount": 299.99,
"currencyCode": "INR"
},
"shippingAddress": {
"firstName": "John",
"lastName": "Doe",
"address1": "123 Elm Street",
"city": "Anytown",
"country": "IND",
"zip": "12345"
},
"contactInfo": {
"email": "[email protected]",
"phone": "911234567890"
},
"statusUrl":"https://example.com"
}
}'
Order Cancelled Event
When an order is cancelled, make a POST request to our customServerEvent API to create an order_cancelled event. Make sure to send the the uniqueOrderId in the payload property to trigger the event for the correct order
curl --location 'https://api.spurnow.com/pixel/customServerEvent'
--header 'Authorization: bearer YOUR_API_KEY' \
--header 'Content-Type: application/json' \
--data-raw '
{
"time": "2024-01-27T12:00:00.000Z",
"eventName": "order_cancelled",
"payload": {
"uniqueOrderId": "r2dzrvgyii8cswwfkbuak"
}
}'