Installation

It only takes a few minutes to install the SWARM Events Javascript SDK on your site or landing page. Once installed, you'll be able to track the various actions users make while interacting with your web page. A

Admin Role Required

To Access the Administration section within the SWARM App, you must have an Admin Role. You can learn more about Roles on the Roles & Permission Page

Copy the Javascript Code

After getting setup with an instance of the SWARM Platform, first open up the navigation panel on the left and click on the "Administration" link. From there, click on the Events Tab and see the Installation section.

Once you've navigated to this part of the SWARM Platform, you should see a block of Javascript code that looks similar to this.

<script src="https://cdn.aiadvertising.com/swarm/events/events.min.js></script>
<script>
    events.activate('WORKSPACE_ID');
    events.page('PAGE_NAME')
</script>

Please Note

The value for WORKSPACE_ID should be replaced with your organization's SWARM Workspace ID. You should also replace PAGE_NAME with a name that describes the current web page.

To install this code, either highlight and copy the code or click the "Copy To Clipboard" button in the top right hand corner of the code editor. This will copy the javascript to your system's clipboard.

Install On Your Website or Landing Page

Once you have successfully copied the javascript code to your clipboard, you should paste the code right before the closing body tag of every page where you want the Events snippet to be able to record events.

Activation

Before you are able to create and track any events, you must call the activate function. To activate, you will need to provide your swarm WORKSPACE_ID and any additional options.

The Activate function would look like the following on your website or landing page:

<script>
events.activate(workspace_id: string, options?: object)

// example
events.activate('kaizen_corp', {timeout: 1500});

The Options object is optional and currently has the following options. These can be helpful if you would like to tweak the default behavior of the events snippet or if you need to change the default events endpoint for development purposes.

Option	Type	Description
timeout	number (milliseconds)
url	string (valid url)
debug	boolean (true/false)

Test that it's working

Once you've pasted the Events.js code to your web page and submitted at least one event (the events.page('PAGE_NAME') code above) - you can view these events from the SWARM app.

To ensure the events are successfully being sent to SWARM, navigate to Administration > Events.js & click on the Debugger tab.

The Debugger tool is a real-time tool that helps you confirm that API calls made from the Events snippet or direct HTTP Calls are being received by SWARM. You can use this section to easily troubleshoot issues and visually see which events are being sent to the SWARM Platform.

Tip: The Debugger only shows a sample of the latest events so you may not be able to find events created prior to the latest day.

Start Tracking More Events

Once you've added this code to your page, and validated that you can successfully send data to SWARM - you are ready to start tracking more events! 🎉

To Learn more about the various types of events that can be tracked, and how to add additional javascript to your page to capture this data - check out the Sending Events guide on the next page.

A Note on UTM Query Parameters

UTM query parameters are a powerful way to persist information about the particular Advertisement or Campaign a user has interacted with that has led them to your website or landing page.

Want to learn more about the history of UTMs?

Check out this Wikipedia article which outlines the purpose of UTMs and the most common UTMs used by Advertising Platforms- https://en.wikipedia.org/wiki/UTM_parameters

The most commonly tracked UTMs are:

Parameter	Purpose
utm_source	Identifies which site sent the traffic
utm_medium	Identifies which type of link was used
utm_campaign	Identifies a specific campaign
utm_term	Identifies search terms
utm_content	Identifies what specifically was clicked to bring the user to the site

For any event sent via SWARM Events, the query parameters are automatically tracked and parsed. This makes it easy to understand which advertising, campaign, persona, and other key information led to the user interacting with your page.

Depending on the platform, you can also add your own query parameters to the URL. Anything added as a valid query param will be tracked against the event.

For example, the following url:

https://krugerindustries.com/landing/page/name?utm_source=fb&utm_medium=ditial&utm_campaign=fun_freddy&other_param=custom_value

Would be parsed by SWARM Events and added to any events sent from that page as the following.

{
    utm_source: "fb",
    utm_medium: "digital",
    utm_campaign: "fun_freddy",
    other_param: "custom_value"
}

Need Help Setting up the SWARM Events.js?

We get it, not everyone has a developer that can set this up for them - if you would like one of our expert to assist you setting up and validating that everything is wired up correctly - please contact us at [e-mail] and we'd be happy to help.