Sending Events

This page provides guidance on how to use SWARM Events to capture meaningful data about anonymous and known customers.

Once you have activated the Events script on your website or landing page, you can begin to capture data by ending events.

The Events Javascript SDK currently tracks the following events:

1. Identify - who is the customer?

2. Track - what are they doing?

3. Page - what web page are they on?

4. Group - what group(s) or organizations are they a part of?

By using a combination of these events, SWARM can get a clear picture of the behaviors and actions of users online. This can be crucial to attributing marketing campaigns and refining your messaging in a way that is relevant to your customers.

Please Note

In order to send events - you must first ensure the Events JS SDK is activated on the page - please see Installation > Activation to learn more about activating SWARM Events on your website or landing page.

Event Types & Usage

The SDK makes sending these types of events very simple. For each type of event, you can simple add a couple lines of javascript and the library will take care of the rest.

See each section below to learn how to send the various types of events.

Identify

The identify action allows us to identify a particular customer. Once a user is identified, the SWARM Events SDK - adds a cookie to the users browser so any subsequent events will be tied to this user.

Please Note

The Events SDK will keep a cookie in place for a rolling 7 days. Each time a user takes an action, we extend the cookie for another 7 days. After a week, if there are no actions - the script expires the cookie and another Identify action will need to take place.

SWARM recommends that you make an Identify call:

• After a user fills out a form

• After a user first registers for the application

• When a user updates their information

• Upon loading any pages accessible by a logged in user

If you are able to receive first party data about a user - calling identify will help SWARM relate any additional events back to this individual.

Here is the payload of a typical identify call.

{
    "type": "IDENTIFY",
    "anonymous_id": ""
    "user_id": "465873497"
    "traits": { 
        firstName: "George"
        lastName: "Costanza",
        title: "Sales Manager",
        email: "[e-mail]",
        company: "Kruger Industrial"                
    },
    "data": {}
}

And here's the corresponding javascript & payload.

// javascript call
events.identify('userId': string, traits: object, data: object);

// example
events.identify("465873497", {
    firstName: "George"
    lastName: "Costanza",
    title: "Sales Manager",
    email: "[e-mail]",
    company: "Kruger Industrial"
},{
    landingPage: "Sales Association Whitepaper"
});

The identify payload has the following fields:

Field	Type	Required	Description
userid	string	optional, if anonymous_id is set instead	Unique identifier for this user. Usually this is an ID tied to a form submission or the id of the user in a database.
traits	object	optional	Free-form object of traits of the user. This may include things like name or email. See Traits below for additional examples of relevant information to send with events.
data	object	optional	Send along any additional information that you would like to track with this event. This is sometimes used to track system type data.

Track

The track event is how you can record any actions your users perform, along with any properties that describe the action.

Here are a few examples:

• a user clicks a call to action button

• a user downloads an E-Books

• a user signs up for a subscription

• a user initiates a VOIP call to sales

• any other action relevant to your users buyer journey!

Anything that might be relevant to understanding a customers buyer journey can be sent to SWARM to enhance your overall view of the customer and to tailor their experience.

Please Note

It can be very helpful to call the identify event before sending Tracking events. This will allow SWARM to tie all of those events to a single user.

You can also send any additional information along with the event to help provide context on what they are doing. For example, if they click a CTA button, you can send the name of the button or if they sign up for a subscription you can send the plan and price of the plan they signed up for.

Here's the payload of a typical track event:

{
    "type": "TRACK",
    "action": "Downloaded E-Book",
    "traits": { 
        "name": "Modern AI in Advertising"               
    },
    "data": {}
}

And here's the corresponding Javascript & payload:

// javascript call
events.track(action: string, traits?: object, data?: object); 

// example calls
events.track("Download E-Book", {
      name: "Using AI In Advertising"
});

events.track("Lead Form Submitted", {
      interests: ["Fishing","Hiking","Camping"],
      age_range: "40-50"
});

The track call payload as the following fields:

Field	Type	Required
action	string	required
traits	object	optional
data	object	optional

Page

The page event can be used to track Page Views of a given website or landing page. This can be used with both identified and anonymous users and can help provide visibility into what pages are most viewed and whether an individual viewed a page on multiple occasions.

The page call has the following payload:

{
    "type": "PAGE",
    "page": "About Us",
    "data": {}
}

And here's the corresponding javascript & payload:

// javascript
events.page(page: string, data?: object);

// example
events.page('About Us', {});

The page call payload has the following fields:

Name	Type	Required
page	string	required
data	object	optional

Group

The Group event can be used to cluster either anonymous or identified users that are visiting your web page. This event can be helpful to track which organizations, associations, or even persona groups are visiting your page.

Examples of groups that may be helpful to track in SWARM:

• The company they work for (Abc Industries)

• The Industry the person is apart of (Manufacturing, Distribution, etc)

• Persona (direct_danny) - this may be known based on a uniquely built landing page, etc

A single user_id or anonymous_id can be added to multiple groups. This can be helpful to understand the various organizations or interests a single person may have across multiple campaigns, landing pages, etc.

The group call has the following payload:

{
    "type": "GROUP",
    "group_id": "ABC_CORP",
    "traits": {
        "name": "Abc Corporation",
        "website": "http://abc-corp.com"
    },
    "data": {}
}

And the corresponding Javascript & payload:

// javascript
events.group(group_id: string, traits?: object, data?: object);

// example
events.group('VIP');

The group call payload as the following fields:

Name	Type	Required
group_id	string	required
traits	object	optional
data	object	optional