How-to listen Web Socket events and Implement IFX email service provider

Keeping Arc XP Subscriptions data in sync with your other systems, including your email newsletter system, is vitally important. Arc XP Subscriptions streams all relevant events via WebSocket, allowing for easy integration.

How to listen to WebSocket events

You can listen to Arc events by opening a WebSocket connection to

wss://{base_URL}/retail/api/v1/event/stream/{index}

When generating a Developer Token, general use cURL also contains the base_URL that you can use to create a WebSocket connection.

index is the starting point of the stream of messages in Unix time. You can stream all existing messages by passing in 0 as the index. Default TTL for messages is 14 days. Ideally, you can keep track of the index of your last processed event and any future connections can be opened with that index as the starting point so that you don’t replay messages that you have already handled.

Event Message Structure

All messages have the same structure, and all events are documented in the JSON format:

{
  // Identifies the position of the stream, a sequential id of the message
  "index": "1556553823611",
  // The key that client code can use to handle different actions per message based on its type
  "type": "EVENT_TYPE",
  // Containing its own JSON or text structure
  // changes based on the value of the "type" field
  "message": {
    "identifier": "mail@wapo.com",
    "uuid": "753750ac-7c84-40a3-8178-8bf5cbd66653",
    "email": "mail@wapo.com"
  },
  // Provides the Epoch time when the event occurred
  "eventTime": 1556553823611
}

Sample message payload

{
  "index":"1551207953693",
  "type":"MY_TYPE",
  "message": {
    "test":"demo message 1551207953693"
  },
  "eventTime":1551207953693
}

Ways to connect to the stream

API Browser

Create a WebSocket request in the API browser of your choice e.g. Postman, Insomnia.

  wss://{base_URL}/retail/api/v1/event/stream/{index}
  Headers: {
    Authorization: {ARC_ACCESS_TOKEN}
    Arc-Site: {siteID}
  }

Node

Install Node https://nodejs.org/en/
Install a Node.js WebSocket library, run npm install ws
cd to your working directory
Run npm init
Create file named app.js with the below javascript. Replace domain with your domain.
Run node app.js

var WebSocket = require('ws')
var options = {
    headers: {
        "Arc-Site": "siteID",
        "Authorization": "Bearer {ARC_ACCESS_TOKEN}"
    }
};
const connection = new WebSocket('wss://{base_URL}/retail/api/v1/event/stream/{index}', options)
connection.onopen = () => {
    setInterval(function () {
        connection.send('ping');
    }, 5000);
    console.log('Connection Established');
}
connection.onerror = error => {
    console.log(`WebSocket error: ${error.message}`)
}
connection.onmessage = e => {
    var obj = JSON.parse(e.data);
    if(obj.type !== 'PONG'){
        console.log(obj)
    }
}

SendGrid Email Service Provider Connector using IFX

Many of our clients use email service provider (ESP) to effectively manage and execute email marketing campaigns, resulting in improved deliverability, engagement, and ultimately business growth. However, it may be a bit cumbersome for clients currently to manually connect Arc Subscriptions WebSocket events to their ESP. Today we will be showing how to create integration between Subscriptions and SendGrid using IFX Node.js implementations. This will allow clients to send transactional emails triggered by the Subscription events. Many of our clients may already have an ESP of choice for marketing purposes and this integration can be also extended to easily send emails with the existing ESP.

Arc XP’s Subscriptions make setting up your email service provider (ESP) quick and painless with our extendable Connector. The Connector utilized IFX to create an integration between Subscriptions WebSocket events and SendGrid. Want to continue using your preferred ESP? Just extend this Connector using this guide. You will be up and running quickly and then can move on to tailoring your marketing and transactional emails for your business.

How to configure IFX ESP integration

Create IFX integration

Create IFX integration by calling /admin/integration. If you are having trouble, please read through detailed guidelines in the IFX documentation.
Download a zip file of the bundled code

Call /admin/bundles/{integrationName}/download/{bundleName} to download template bundle.
Subscribe to the desired events using IFX subscriptions API

Below is an example API call enabling commerce:VERIFY_EMAIL event in subssinglesite sandbox environment. Make sure that the event name is in all capital letters. This should be done for each event that you’d like your integration to listen to.
Modify the template code

Disclaimer: Recipes are reference implementations intended to help developers get started more quickly, but are not guaranteed to cover all scenarios nor are they supported by Arc XP. They are are provided “as is” and Arc XP is not responsible for it after you begin using it. Recipes may be updated to incorporate best practices or new solutions at the sole discretion of Arc XP.
- Download and unzip subssinglesite-esp-subssinglesite-1-0-0 2.zip and copy the code in the src to the newly created repository. If you do not have access to this, please submit an ACS request.
- Follow the readme on the template code to install NPM packages and run the local testing server
- @sendgrid/mail would need to be installed on top of what’s already on the template code
- More details on running the app locally can be found here
- For secrets and sensitive information such as the SendGrid API key, you should store these values by following this guide
- For non-sensitive information, such as CDN_ENDPOINT, EMAIL_SENDER, and WEB_SITE_URL, these can be stored in the respective environments (.env.development, .env.sandbox, and .env.production)
- You will need to update templateId used in each email handler with the values from dynamic templates from your SendGrid account as well as variables in the .env files
eventsRouter.json determines which event gets routed to a specific handler. For example, when commerce:VERIFY_EMAIL event is triggered, logic inside the verifyEmailHandler will be executed. The events emitted by Arc Subscriptions include predefined data on these events but if you want some custom data, you can call developer API from the event handler to get the data and use those in the dynamic email template. For example, if the firstName was not provided, a developer can call a developer API with PAT and use the result to populate the dynamic template.
Set up a SendGrid account

Use this link to get started with SendGrid.

Note: For this implementation, we’ve created an account and verified the account as a single sender verification.

Create an API key under the account.

Create dynamic templates to be used with different events

You’ll need template ids later in the guide.

The dynamic template uses Handlebars. {{}} can be used to insert variables and test data can be inserted to preview the email
Bundle, Deploy, Promote

Follow this guide to bundle, deploy and promote your integration.
Debugging and Testing
- You can test your code locally by starting up a local server by running npm run localTestingServer and then sending POST requests to http://127.0.0.1:8080/ifx/local/invoke to verify that your handlers are behaving in the expected way
- Keeping a WebSocket connection live while testing events can be helpful in verifying that the events are being triggered.
- You can also use the IFX log API. Initialize the log search by calling /admin/logs/integration/{integrationName} then view results by calling /admin/events/subscriptions
- Detailed IFX guide on how to use log API can be found How to Use Integration Logs with IFX
- You can use console.log in event handlers for testing and debugging as it’ll show up on the IFX logs
- More information on debugging: Debugging and Testing Deployed Integrations