Sending Events

Tracking user interaction to gather information which can be used to define Audiences.

Ninetailed profiles are created and updated by sending events about that profile to the Experience API. Rather than interacting with the Experience API endpoints directly, the principal way to send events is to use the methods made available from the Ninetailed JavaScript SDK.

A Ninetailed class instance created by any of Ninetailed's SDKs composed from the JavaScript SDK provides three methods for sending events: page, track and identify.

page

type Page = (properties?: Object) => Promise<void>;

A page event indicates a user has viewed the current page. The SDK provides a context object describing the parameters of page that has been viewed including the referrer, url, path, user-agent and other properties to be consumed by the API.

While most of the time you will call this page method with no arguments, you may optionally specify any properties you would like to associate with the page view event. This can be useful for when creating Audiences. For example, if the category to which viewed blog posts belong is not contained within the URL of the blog posts but you'd like to create an Audience of visitors who have viewed blog posts of a certain category a certain number of times, you can pass the category along in the argument:

page({'category': 'YOUR_BLOG_CATEGORY'})

Our Next.js and Gatsby SDKs automatically call a page event on every route change. If your application uses the React SDK or JavaScript SDK, you should manually implement a page call on every route change.

track

type Track = (event: string, properties?: Object) => Promise<void>;

track events are used to log specific named actions a user takes, like signup or registered_for_newsletter. Events can be named anything you like.

Track events may also accept a properties argument detailing additional information. For example, you might include the SKU and quantity of items on an add_to_cart event.

track('add_to_cart', {sku: '9T41L', quantity: 1})

In addition to serving as an Audience rule, track events are used to indicate the conversion events you want to measure in Experience Insights.

identify

type Identify = (uid: string, traits?: Traits) => Promise<void>;

Identify events serve two purposes:

First, identify allows you to add custom information, called traits, to a profile. Traits can be any attribute of interest about a customer. Any valid JSON is a valid trait. You can store any information of interest on profiles that you may want to use to segment users. For example, you might store a user's responses from a sign up form, a list of products they recently visited, or data from an upstream source of your customer data like a CRM or CDP.

identify('', { favoriteColor: "red" })

Second, identify allows you to name or "alias" a profile such that it can be referenced by that same alias in the future. IDs stored within an analytics system, customer data platform, or e-commerce platform make ideal aliases.

identify('customer12345')

After aliasing a profile, you can reinstate the aliased profile on a different device or browser by calling identify again using the same supplied alias. This merges the latest activity of the current profile with the profile at that alias. For personalizations and experiments served to logged in users, you will likely want to call identify after each successful authentication.

The flexibility of identify is powerful but should be used with caution. In particular, you should consider what privacy legislation your application needs to abide by, and whether that affects what data should not be stored as traits. For example, you probably would not want to store contact information (email addresses, phone numbers, etc.) as traits or use them as aliases.

Accessing Event Methods

React, Next.js, Gatsby

The useNinetailed hook provides the tracking functions page, track, and identify. These methods will call the Experience API using the configuration parameters supplied to a <NinetailedProvider>.

import React from 'react';

import { useNinetailed } from '@ninetailed/experience.js-react';
// or import { useNinetailed } from '@ninetailed/experience.js-next';
// or import { useNinetailed } from '@ninetailed/experience.js-gatsby';

export const myComponent = () => {
  const { page, track, identify } = useNinetailed();
  
  page();
  identify('anAlias', {someTrait: "value"});
    
  return (
    <button 
      type="button" 
      onClick={() => { track('add_to_cart'); }}
    >
      Add to Cart
    </button>
  );
}

JavaScript

The page, track, and identify methods are available directly on a Ninetailed class instance.

import { Ninetailed } from '@ninetailed/experience.js';

const ninetailed = new Ninetailed({ clientId: "NINETAILED_API_KEY"})

ninetailed.page();
ninetailed.track('myEvent')
ninetailed.identify('alias', {traitName: "traitValue"})

See the Ninetailed Instance documentation for a full list of configuration options and methods available from the JS SDK.