Experience API

Updating and receiving information of a user profile.

The Experience API is the core of Ninetailed. It returns profiles, JSON representations of visitors and their activity, in response to events. The Experience API is highly performant because of it's deployment on the edge.

Endpoints

Batch Creating or Updating User Profiles

You might also use the endpoints of this API to push data from your own existing customer data systems into Ninetailed profiles in real time, in periodic batches, or in bulk as part of a first-time migration.

This endpoint upserts profiles, meaning that when events are passed for profile IDs that do not yet exist profiles at those IDs will be created. This ensures that you do not have to check whether profiles at specific IDs exist prior to migration.

This endpoint is intended to be used server-side. Because of that, it does not accept options to related to resolving location or IP address. You may, however, still specify location data on events.

This endpoint accepts up to 200 events, with a maximum of 50 identify events, across a maximum of 50 unique profiles.

Tips

  • We highly recommend that you use the profileID that is returned by the Ninetailed profile once you have identified the user. Retrieving and updating profiles with this returned ID is more performant than using an ID you have supplied when creating or aliasing a profile.

  • The payload you supply to these endpoints can be sent with the content-type header set as either application/json or text/plain. We recommend that you use text/plain whenever possible to minimize request roundtrip time by avoiding triggering a CORS preflight request. Our SDKs automatically send requests as text/plain.

  • If you want to ensure that a user's location is not resolved is part of a create profile or update profile endpoint request, you can either:

    1. Set an empty string or object, whichever is applicable, to each context.location argument, OR

    2. Not set location or supply location: undefined or location: {} , do not supply location as an option, and set context.library.version to a string that represents a semver of 3.14 or greater.

Types

Response

The returned response of each API endpoint is a data structure indicating the complete representation of the profile(s) and the Ninetailed Experiences & variants that the Experience API has selected for the profile(s). Endpoints that only alter one profile (Create, Update, and Get), only a single profile is returned, while the Batch Upsert Profile Point returns an array of altered profiles.

/**
 * One or more ProfileWithSelectedVariants oojects are returned, dpeending on the endpoint uses
 */ 
type ProfileWithSelectedVariants = {
    profile: Profile;
    experiences: SelectedVariantInfo[];
};

Profile

A profile is a a wholistic representation of a single user. The Ninetailed Experience API computes and returns a visitor's profile in response to page, track, and identify events. The profile is also used within Ninetailed's Experience SDKs to determine the appropriate experience variants and Merge Tag values to render.

type Profile = {
    id: string;
    stableId: string;
    random: number;
    audiences: string[];
    traits: Record<string, any>; // Any valid JSON
    location: {
        coordinates?: {
            latitude: number;
            longitude: number;
        } | undefined;
        city?: string | undefined;
        postalCode?: string | undefined;
        region?: string | undefined;
        regionCode?: string | undefined;
        country?: string | undefined;
        countryCode?: string | undefined;
        continent?: string | undefined;
        timezone?: string | undefined;
    };
    session: {
        id: string;
        isReturningVisitor: boolean;
        landingPage: {
            path: string;
            url: string;
            query: Record<string, string>;
            referrer: string;
            search: string;
        };
        count: number;
        activeSessionLength: number;
        averageSessionLength: number;
    };
}

Experience

Each response from the Experience API also returns an array of experience assigned to the profile. you may see this typed in the SDKs as `SelectedVariantInfo Experiences must be published in the content source to be returned on the Experience API. Each experience indicates the variant index (0 = control, 1 = variant 1, etc.) and the content source IDs of content to show.

type Experience = {
    experienceId: string;
    variantIndex: number;
    variants: Record<string, string>;
}

type SelectedVariantInfo = Experience; // The type name used in our SDKs

The key of each variants Record is the content source's ID of the baseline or control content. The value of each variant Record is the content source's ID of the applicable variant content. When the variant index is 0, the key and value are the same, otherwise they will be different.

Example Experiences
{
    "experiences": [
        { "experienceId": "1", "variantIndex": 0, "variants": {"entryA": "entryA"}}
        { "experienceId": "2", "variantIndex": 1, "variants": {"entryB": "entryC"}}
    ]
}

Event

Each POST endpoint accepts arrays of events as part of requests. Events are the building blocks of profiles; they indicate the actions taken and attributes of individual profiles so those profiles can be segmented into Audiences.

type Event = {
  anonymousId: string; // Only when using the batch endpoint, otherwise the anonymous ID is in the URL
  channel: 'web' | 'mobile' | 'server' | 'client';
  context: {
    app?: {
      name: string;
      version: string;
    },
    // Powers `has viewed page` UTM parameter Audience conditions
    campaign?: {
      name: string;
      source: string;
      medium: string;
      term: string;
      content: string;
    },
    // Describes the library making the request
    library: {
      name: string; 
      version: string;
    },
    locale?: string; // ISO 639-1 + ISO 3166-2, e.g., "en-US"
    // Optionally supply an object to merge with API-resolved location, if the option is set
    location?: {
      coordinates?: {
        latitude: number;
        longitude: number
      },
      city?: string; // Use proper capitalization of the city name
      postalCode?: string;
      region?: string;
      regionCode?: string; // ISO 3166-2
      country?: string;
      countryCode?: string; // ISO 3166-2
      continent?: string;
      timezone?: string;
    },
    // Used for various `has viewed page` Audience conditions
    page?: {
      path: string;
      query: Record<string, string>; // Object of query:value pairs
      referrer: string; // Use full URL including protocol, path, and query string
      search: string; // Full querystring, e.g., "?query=value"
      url: string; // Use full URL including protocol, path, and query string
    }
    userAgent?: string
  }
  messageId: string; // Generate a UUID
  timestamp: Date; // Typically assigned as Date.now()
  type: "page" | "track" | "identify";
  event?: string; // Required when type === "track"
  userId?: string; // Required when type === "identify"
  traits?: Record<string, any>; // Any vaild JSON. Required when type === 'identify'
  // Required when type === "page" or type == "event"
  properties?: {
    // The following five properties must be set when type === "page"
    // Not required for events of type == "track"
    path: string;
    query: Record<string, string>; // Object of query:value pairs
    referrer: string; // Use full URL including protocol, path, and query string
    search: string; // Full querystring, e.g., "?query=value"
    url: string; // Use full URL including protocol, path, and query string
    // Any additional properties that can be parsed as valid JSON may be set here
    [string]?: any;
  }
}

Options

The API endpoints also accept options to modify the behaviour of the request. These are available only on the create profile and update profile endpoint (not the batch upsert endpoint).

type CreateOrUpdateProfilePayload = {
    events: Event[];
    options?: Options;
}

type Options: = {
    features?: Feature[];
}

type Feature = "location" | "ip-enrichment"

  • Specifying location will attempt to resolve the location of the user based on the IP of the request and where it ingresses to the Experience API.

    • If you do not want location to be resolved when sending events, do not add location as a feature option and ensure that context.library.version is set on any accompanying event as a string representing a semver greater than 3.14

  • Specifying ip-enrichment will attempt to resolve firmographic data with a connected Albacross API Key. See Albacross for more information.

Traits

traits are arbitrary JSON data set by identify events. Traits are shallow merged together; the most recent value of a given trait key overwrites the prior value.

Traits are useful for custom segmentation using has trait rules. Additionally, traits can serve as snippets for dynamic inline personalizations.

Example for an inline Personalization:

const headline = `Hey ${profile.traits.firstname}👋`.

type Traits = {
  [key: string]: string | number | boolean | Traits;
};

// example
const traits: Traits = {
  "firstname": "Max",
  "address": {
    "street": "Allee 33"
  },
  "company": "Wayne Enterprises, Inc."
}
PreviousGetting StartedNextExperience SDK

Last updated