JavaScript Source: Getting Started

  Sign up for early access!

Apply for early access to be among the first to try out Data Pipelines. Bear with us: it may take a few weeks for us to approve your request as we're actively working on CDP.

Add our JavaScript library to your website or app to send events representing your website visitors and users to one or more destinations. This library makes it easy—and in some cases, automatic—to send events into and other destinations.

How it works

Our JavaScript source library helps you send data from your website to any of our destinations. This is our most versatile and necessary source, supporting all of our destinations—whether they’re in cloud or direct-connection modes.

When people visit your website, you’ll want to identify them. The identify method is fundamental to the CDP, providing a unique identity for a person that we can use across sources and destinations. After you identify a person, subsequent calls reference the identified person for the remainder of the client’s session on your site.

You can still generate events before you identify someone. These events are anonymous. When you identify a person, we’ll automatically associate the identified person and their anonymous activity, giving you a complete view of your audience’s activity on your site.

Want to learn more? Check out the our API reference.

flowchart LR a(person
visits site)-->|generate
anonymousId|z subgraph z [anonymous activity] direction TB b(visit
a page) b-->|page|c(add item
to cart) c-->|track|d(person
logs in) end subgraph y [identified activity] direction TB e(person initiates
checkout)-->|track|f(person finishes
transaction) f-->|track|g(person logs out) end d-->|identify|e g-->|reset|h(person is
anonymous again)

Set up your JavaScript Source

As a part of this process, you’ll need to copy some code into the head tag of your website. You don’t have to do this right away, but your source won’t begin capturing information until you copy this tag to your website. You’ll also want to remove third party code for any destinations that you want to connect to your website source, otherwise you’ll send duplicate information to your destination—once through the CDP and once with native code!

  1. Go to the tab and click Sources.

  2. Click Add Source, pick JavaScript, and click Next.

  3. Give the source a Name and click Submit. The name is simply a friendly name to help you find and recognize your source in

  4. In your new source, under Installation instructions, copy the Sample Code.

    Your code looks like this, though yours will have a real API Key in the analytics.load statement.

     !function(){var||[];if(!analytics.initialize)if(analytics.invoked)window.console&&console.error&&console.error("Snippet included twice.");else{analytics.invoked=!0;analytics.methods=["trackSubmit","trackClick","trackLink","trackForm","pageview","identify","reset","group","track","ready","alias","debug","page","once","off","on","addSourceMiddleware","addIntegrationMiddleware","setAnonymousId","addDestinationMiddleware"];analytics.factory=function(e){return function(){var;t.unshift(e);analytics.push(t);return analytics}};for(var e=0;e<analytics.methods.length;e++){var key=analytics.methods[e];analytics[key]=analytics.factory(key)}analytics.load=function(key,e){var t=document.createElement("script");t.type="text/javascript";t.async=!0;t.src="" + key + "/analytics.min.js";var n=document.getElementsByTagName("script")[0];n.parentNode.insertBefore(t,n);analytics._writeKey=key;analytics._loadOptions=e};analytics.SNIPPET_VERSION="4.15.3";
  5. Go to your website and paste this code directly before the closing </head> tag.

Now you’re ready to use the snippet to identify people and send events to destinations!

 Your API Key is exposed

When you use our JavaScript source, your API Key is exposed on the client side. This key is only used to send data into But, if you’re concerned about security, you might want to use our Node.js package instead.

What can I do with the snippet?

When you add the snippet, it’ll begin tracking anonymous pageviews. This is similar to the way Google Analytics works.

However, you’ll need to identify your audience to take advantage of most analytics and marketing tools. You can do that with the identify method described below. This is enough to use most basic CRM functionality—like in Salesforce or Intercom.

But, lots of analytics can do more than record identities. You can get the most out of platforms by recording the actions that people perform on your website. that’s what you can do with the track call.

Identifying Users

The identify method tells the CDP who the current website visitor is, and lets you assign unique traitsA key-value pair that you associate with a person or an object—like a person’s name, the date they were created in your workspace, or a company’s billing date etc. Use attributes to target people and personalize messages. to a person.

You should call identify when a user creates an account, logs in, etc. You can also call it again whenever a person’s traits change. We’ve shown a typical call with a traits object, but we’ve listed all the fields available in an identify call below.

You can send an identify call with an anonymousId and/or userId.

  • anonymousId only: This assign traits to a person before you know who they are.
  • userId only: Identifies a user and sets traits.
  • both userId and anonymousId: Associates the data sent in previous anonymous page, track, and identify calls with the person you identify by userId.

Before you identify someone, their activity is anonymous. We’ll automatically assign unidentified people an anonymousId so you can still send page and track events. But when you identify a person, we’ll automatically associate the identified person with their anonymous activity, so you have a more complete view of your audience’s activity.

analytics.identify('f4ca124298', {
  email: ''
  first_name: 'cool',
  last_name: 'person'

That identifies Cool Person by their unique User ID (f4ca124298—the value you know this person by in your database) and sets their first_name, last_name and email traits. Traits are information that you want to record about your audience in your various destinations.

In general, we recommend that you inject an identify call into the footer of every page of your site where a user is logged in. That way, no matter what page the user first lands on, they are always identified.

Identifying people by their email address

In and some other destinations, you can identify people by their email address. If you use these destinations, you can send identify calls without a userId as long as your request includes an email trait.

Stop identifying people (logout)

When someone comes to your website, we’ll assign them an anonymousId. When they log in or provide information you can use to identify them, you’ll use the identify method. This stores their identity to a cookie and local storage, so you’ll recognize them when they come back to your website.

When they log out of your website, you’ll call the reset method to reset their identity. This anonymizes their data again, respecting your audience’s right to privacy.

Tracking events

The track method tells us about actions people take—the events people perform—on your site. Every track call represents an event. When you send an event with a track call, you can provide associated properties about the event. For more information, see the track method reference.

You should track events that are indicators on your site, or the kinds of things that you want to know that your audience does on your website, like Video Viewed, Item Purchased or Article Bookmarked. In some products—like Journeys—you can use events to trigger messages and other downstream actions.

You can send events with an anonymousId or a userId. Calls that you make with an anonymousId are associated with a userId when you identify someone by their userId.

Track calls typically contain an event name—so you know what a user did—and a series of properties, which contain additional information about the event. The examples below show added_to_cart events, containing properties that let you know about the product a person added to their shopping cart.

For example, imagine that you want to send an event when someone begins an online course. You’d send a call that looks something like this:

analytics.track('class_started', {
  title: 'How to use',
  progress: '2%',
  category: 'getting started'

In this case, the event is called class_started. That event contains the title, progress and category properties that tell you more information about the class the person started and why.

If you’re just getting started, some of the events you should track are events that indicate the success of your site, like Signed Up, Item Purchased or Article Bookmarked. You can get started with just a few events and add more later!

Querystring Methods

You can trigger an identify and a track method based on query strings in your URL. This can help you execute calls when tracking visitors from email click-throughs, social media clicks, and digital advertising.

ajs_uidThe userId for an identify call.This triggers an identify call.
ajs_eventThe event name for a track call.This triggers a track call.
ajs_aidThe anonymousId for the current user.If you don’t pass a value, this returns the current anonymousId. If you pass a value, it sets the value as the user’s anonymousId.
ajs_prop_<property>A property you want to pass to a track call.This won’t implicitly trigger an event and is dependent on you also passing ajs_event. This property is included in the resulting track call.
ajs_trait_<trait>A trait for the person in the identify call.This won’t implicitly trigger a call. It’s dependent on you also passing ajs_uid. This trait is included in the resulting identify call.

For example, this URL:

would create the following events on the page.

analytics.identify('123456789abcd', { name: 'Karl Jr.' });
analytics.track('Clicked Email', { 'emailCampaign': 'First Touch' });

Frequently Asked Questions

Will the snippet slow things down for users?

No. Our JavaScript snippet loads code asynchronously, so it won’t affect your page load speed. When the snippet is running on your site, you can enable destinations in your workspace and we’ll start sending data to them automatically.

What should I do with third party destination code?

When you use our JavaScript snippet, you should remove third party destinations from your site, so that you don’t record duplicate information. For example, if you want to send data from your JavaScript source to Google Analytics, you’ll want to remove Google Analytics tracking code from your site otherwise you may double-count visitors and events!

Do I need to update the snippet to support new destinations?

No! You don’t have to do anything to support new destinations.

When you add a new destination in, we’ll automatically route it to the correct destinations—including direct-mode destinations.

When you create (or change!) a Source, we generate a new API Key for that source. You use the API Key in your code to tell our servers where the data comes from, so we can route it to your destinations and other tools.

Copied to clipboard!
Is this page helpful?