Skip to main content
All CollectionsSpur Onboarding Platform Integration Guides
Integrate a custom ecommerce platform without a pre-built Spur integration
Integrate a custom ecommerce platform without a pre-built Spur integration

Learn how to integrate your custom e commerce storefront with Spur

Velma Dinkley avatar
Written by Velma Dinkley
Updated over a week ago

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:

  1. Product Viewed

    When someone clicks on a product or a page on your website

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

  1. Placed Order

    When an order successfully processes on your system.

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

This script is typically added in the Header script of every page so that you can make API calls accordingly

<script 
src="https://r2.spurnow.com/pixel/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.

You integrate this at parts where you collect the number of a user. Typically, you'll add this code at a place right after you do checkouts, popups etc.

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_viewed

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

    When 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

To trigger a server side event, you need to make a POST request to the our API endpoint:

  1. The Authorization header of the request must set as bearer <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.

  2. The request must have a JSON body having the following properties

    1. time - UTC string representation of the time the event was triggered

    2. eventName - the name of the event eg. order_placed

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

  1. time - The time an order was placed at, in ISO 8601 format

  2. statusUrl - Your actual order status url, where a customer can open and check their order status

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"
}
}'
Did this answer your question?