Send and Track Events

You can follow the steps mentioned in the documentation below or refer to our quick code recipe

Pre-requisites

1. Integrate node SDK
2. Create User Profile
3. Create Template on SuprSend platform - if you want to trigger workflow by passing the event
4. Create Workflow on SuprSend Platform - if you want to trigger workflow by passing the event

Create Workflow on SuprSend Platform

For Event based workflow trigger, you'll have to create the workflow on SuprSend Platform. Once the workflow is created, you can pass the Event name ( GROCERY_PURCHASED in below example) defined in workflow configuration with the help of supr_client.track_event method. Variables added in the template should be passed as event properties

Send Event

You can send event to Suprsend platform by using the supr_client.track_event method.

const { Event } = require("@suprsend/node-sdk");

const distinct_id = "distinct_id" // Mandatory, Unique id of user in your application
const event_name = "event_name"   // Mandatory, name of the event you're tracking

// Properties:  Optional, a dict representing event-attributes
const properties = {													
  "key1":"value1",
  "key2":"value2"
}  

const event = new Event(distinct_id, event_name, properties, {brand_id : "default", idempotency_key="__uniq_request_id__"})

// Track event
const response  = supr_client.track_event(event)
response.then((res) => console.log("response", res));

❗️

Event naming guidelines

When you create an Event or a property, please ensure that the Event Name or Property Name does not start with $ or ss_, as we have reserved these symbols for our internal events and property names.

Idempotent requests

SuprSend supports idempotency to ensure that requests can be retried safely without duplicate processing. If Suprsend receives and processes a request with an idempotency_key, it will skip processing requests with same idempotency_key for next 24 hours. You can use this key to track webhooks related to workflow notifications.

To make an idempotent request, pass idempotency_key in the event instance. Idempotency key should be unique that you generate for each request. You may use any string up to 255 characters in length as an idempotency key. Ensure that you don’t add any space in start and end of the key as it will be trimmed.

Here are some common approaches for assigning idempotency keys:

• Generate a random UUID for each request.
• Construct the idempotency key by combining relevant information about the request. This can include parameters, identifiers, or specific contextual details that are meaningful within your application. For example, you could concatenate the user ID, action, and timestamp to form an idempotency key like user147-new-comment-1687437670
• Request-specific Identifier: If your request already contains a unique identifier, such as an order ID or a job ID, you can use that identifier directly as the idempotency key.

Sample Code

const { Event } = require("@suprsend/node-sdk");

// Track Event Example
const distinct_id = "0fxxx8f74-xxxx-41c5-8752-xxxcb6911fb08" // Mandatory, Unique id of user in your application
const event_name = "product_purchased"   // Mandatory, name of the event you're tracking

// Properties:  Optional, a dict representing event-attributes
const properties = {													
  "first_name": "User",
  "spend_amount": "$10",
  "nested_key_example": {
    "nested_key1": "some_value_1",
    "nested_key2": {
      "nested_key3": "some_value_3",
    },
  }
}

const event = new Event(distinct_id, event_name, properties)

// Track event
const response = supr_client.track_event(event)
response.then((res) => console.log("response", res));

🚧

Note

• Event_name in Track event method should exactly match the Event name added in Workflow configurations

Add file attachment in event (for email)

To add one or more Attachments to a Notification (viz. Email), you can just append the filepath of attachment to the event instance.

• Call event.add_attachment() for each file with an accessible URL.
• Ensure that file_path is a publicly accessible URL. Since event API size can't be > 100 KB, local file paths can't be passed in event attachment.

Refer below example for adding attachment in event call

const { Event } = require("@suprsend/node-sdk");

// Track Event Example
const distinct_id = "0fxxx8f74-xxxx-41c5-8752-xxxcb6911fb08" // Mandatory, Unique id of user in your application
const event_name = "product_purchased"   // Mandatory, name of the event you're tracking

// Properties:  Optional, a dict representing event-attributes
const properties = {...}

const event = new Event(distinct_id, event_name, properties)
// this snippet can be used to add attachment to event
const file_path = "https://www.adobe.com/sample_file.pdf"
event.add_attachment(file_path)

// Track event
const response = supr_client.track_event(event)
response.then((res) => console.log("response", res));

🚧

Add Publicly accessible URL in attachment

Please add public accessible URL only as attachment file otherwise it will throw an error 404 not found and workflow will not be triggered

Response

When you call supr_client.track_event, the SDK internally makes an HTTP call to SuprSend Platform to register this request, and you'll immediately receive a response indicating the acceptance status.

Note: The actual processing/execution of event happens asynchronously.

// Response structure
{
    "success": true, // if true, request was accepted.
    "status": "success",
    "status_code": 202,  // http status code
    "message": "Accepted",
}

{
    "success": false, // error will be present in message
    "status": "fail",
    "status": 400, // http status code
    "message": "error message",
}

Bulk API for multiple event requests

You can use Bulk API to send multiple events.

Use .append() on bulk_events instance to add however-many-records to call in bulk.

const { Event } = require("@suprsend/node-sdk");

const bulk_ins = supr_client.bulk_events.new_instance()
// Example
const e1 = new Event("distinct_id1", "event_name1", {"k1": "v1"}) // Event 1
const e2 = new Event("distinct_id2", "event_name2", {"k2": "v2"}) // Event 2

// --- use .append on bulk instance to add one or more records
bulk_ins.append(e1)
bulk_ins.append(e2)
// OR
bulk_ins.append(e1, e2)

// -------
const response = bulk_ins.trigger()
response.then((res) => console.log("response", res));

🚧

Bulk API supported in SDK version 1.0.0 and above

Bulk API is supported in SuprSend node-sdk version 1.0.0 and above. If you are using an older version, please upgrade to the latest SDK version.

How SuprSend Processes the bulk API request

• On calling bulk_ins.trigger(), the SDK internally makes one-or-more Callable-chunks.
• Each callable-chunk contains a subset of records, the subset calculation is based on each record's bytes-size and max allowed chunk-size, chunk-length etc.
• For each callable-chunk SDK makes an HTTP call to SuprSend to register the request.

Add file attachment in bulk API (for email)

Similar to single API call, you can add file attachment to bulk API by appending the attachment filepath to each event instance in bulk API call.

• Call event.add_attachment() for each file with an accessible URL. Ensure that file_path is a publicly accessible URL.
• Since event API size can't be > 100 KB, local file paths can't be passed in event attachment.

Refer below example for adding attachment in bulk API call

const { Event } = require("@suprsend/node-sdk");

const bulk_ins = supr_client.bulk_events.new_instance()
// Example
const e1 = new Event("distinct_id1", "event_name1", {"k1": "v1"}) // Event 1
// this snippet can be used to add attachment to event
const file_path1 = "https://www.adobe.com/sample_file.pdf"
e1.add_attachment(file_path1)

const e2 = new Event("distinct_id2", "event_name2", {"k2": "v2"}) // Event 2
// this snippet can be used to add attachment to event
const file_path2 = "https://www.africau.edu/images/default/sample.pdf"
e2.add_attachment(file_path2)

// --- use .append on bulk instance to add one or more records
bulk_ins.append(e1)
bulk_ins.append(e2)
// OR
bulk_ins.append(e1, e2)

// -------
const response = bulk_ins.trigger()
response.then((res) => console.log("response", res));

🚧

Add Publicly accessible URL in attachment

Please add public accessible URL only as attachment file otherwise it will throw an error 404 not found and workflow will not be triggered

Response

// Response structure
{
  status: "success",
  total: 10, // number of records sent in bulk
  success: 10, // number of records succeeded
  failure: 0, // number of records failed
  failed_records: [],
  warnings: []
}

{
  status: "fail",
  total: 10, // number of records sent in bulk
  success: 0, // number of records succeeded
  failure: 10, // number of records failed
  failed_records: [{"record": {...}, "error": "error_str", "code": 500}],
  warnings: []
}

{
  status: "partial",
  total: 10, // number of records sent in bulk
  success: 6, // number of records succeeded
  failure: 4, // number of records failed
  failed_records: [{"record": {...}, "error": "error_str", "code": 500}],
  warnings: []
}