Quicklizard Help Center

# QL SDK - Server to Server

Instead of installing our JS SDK on your product and payment confirmation pages, you may send us product and payment confirmation events from your backend to our server-to-server SDK events API endpoint.

This kind of integration is more suitable in situations when you're unable to embed our JS SDK in your pages, or when you want to have stricter control over what data is sent to QL.

# Sending SDK events

Server-to-server SDK events should be sent to https://evt.quicklizard.com/events as an HTTP POST request.

SDK events should be send from your backend in product and payment confirmation pages. Please be sure to read our current SDK docs where you can learn about which data should be sent in each page type.

This part of our SDK docs only covers the server-to-server integration and assumes you are familiar with other concepts of using our SDK.

# Product Page View Events

The structure of a single product page view event payload is as follows:

{
  "client_key": "YOUR_CLIENT_KEY", //your QL client key
  "price": 123.41, //product shelf price as float
  "product_id": "123-AA-X23", //product identifier string
  "event": "view", //event name - "view" represents a product page view
  "permalink": "https://yourstore.com/123-AA-X23/", // product URL on your store
  "vid": "DASDAS-#CCCC-NA", //optional anonymous user identifier
  "tags": ["user:new"], //optional tags for this evening
  "channels": ["online"] //optional pricing channels for this event
}

Please Note

  • The vid field is completely optional and is used internally by QL as part of our analytics algorithms.
  • All other fields are required
  • The price field must be a valid float
  • The product_id is the product's unique identifier on your system

# Product Conversion Events

The structure of a single product payment confirmation event payload is as follows:

{
  "client_key": "YOUR_CLIENT_KEY", //your QL client key
  "price": 123.41, //product sale price as float
  "product_id": "123-AA-X23", //product identifier string
  "event": "conversion", //event name - "view" represents a product page view
  "vid": "DASDAS-#CCCC-NA", //optional anonymous user identifier
  "tags": ["user:new"], //optional tags for this evening
  "channels": ["online"], //optional pricing channels for this event
  "units": 3 // optional number of sold units
}

Please Note

  • The vid field is completely optional and is used internally by QL as part of our analytics algorithms.
  • All other fields are required
  • The price field must be a valid float and contain the total sale price of a given product (in case of multiple sold units, the value should be sale-price/unit X units)
  • The product_id is the product's unique identifier on your system
  • Conversion event channels field should only contain a single channel, despite being passed as an array
  • The units field is optional - It can be used to specify the number of sold units

# API Request format

The server-to-server API supports sending one or more events, as an array of JSON objects, as described above.

For example, in your product page, you will send an HTTP POST request for a single page-view event:

curl -XPOST https://evt.quicklizard.com/events -d '[{
  "client_key": "YOUR_CLIENT_KEY",
  "price": 123.41,
  "product_id": "123-AA-X23",
  "event": "view",
  "permalink": "https://yourstore.com/123-AA-X23/",
  "vid": "DASDAS-#CCCC-NA",
  "tags": ["user:new"],
  "channels": ["online"]
}]'

In the payment confirmation page, you might have more than one product that was bought, and therefore will send multiple conversion events:

curl -XPOST https://evt.quicklizard.com/events -d '[{
  "client_key": "YOUR_CLIENT_KEY",
  "price": 123.41,
  "product_id": "123-AA-X23",
  "event": "conversion",
  "vid": "DASDAS-#CCCC-NA",
  "tags": ["user:new"],
  "channels": ["online"]
},
{
  "client_key": "YOUR_CLIENT_KEY",
  "price": 60,
  "product_id": "455DD-AA-X23",
  "event": "conversion",
  "vid": "DASDAS-#CCCC-NA",
  "tags": ["user:new"],
  "channels": ["online"],
  "units": 3
}]'

Please Note

The POST payload is a JSON-formatted array of event objects. In the above example, the second event specifies a units value of 3, meaning 3 units of that product were sold. In that case, the price field contains the total paid price for 3 units (eg. if one unit costs 10EU the price field will be 30, which is 3 units X 10EU per unit).

# API Response Format

The API will respond with a JSON containing 3 array fields for processed events, failed events and processing errors.

  • processed - events that were successfully parsed and sent to our backends
  • failed - events that were not parsed due to errors in event structure
  • errors - event parse errors
{
  "processed": [{...}],
  "failed": [{...}],
  "errors": [{...}]
}

# Server-to-Server API endpoint

When setting up server-to-server integration, it's important to make sure you send events to the correct set of servers that are configured to handle data for your account.

This information is available in our UI under Settings > Integration Settings. The value of the SDK server-to-server API endpoint is listed there, as shown in the following example.

S2S Endpoint

Important!

Sending SDK events to an incorrect endpoint will result in a loss of data.

# Integration Notes

Since HTTP requests are blocking, calling the QL SDK API from your backend could potentially slow down your page rendering time. There are many reasons why this can happen - DNS failure, network outage, traffic and load spikes, etc.

To ensure minimal disruption to your server-side rendering speed, we recommend that consider the following points:

  • Whenever possible, make as few requests as possible to QL SDK API. For example, in your payment confirmation page, you can send a single request with all purchased items
  • Log API calls to QL SDK API, including request/response times, to help you identify any potential points or use-cases that may slow down rendering times.
  • For medium-high traffic sites, consider collecting product and payment confirmation events from your backend in a queue and sending them asynchronously.
  • If your server-side is written in a language that supports async I/O (Node.js, Java, Go), it's worth considering making API calls to QL asynchronously.
  • Use an HTTP client that supports timeouts, and set that timeout to a low value. This will cause slow HTTP requests to fail, rather than block your server-side rendering process.
  • Log HTTP client failures, in particular if you lowered the default request timeout.

← Server-side implementation →