behavior-events.js

/**
 * The `Entity` object.
 *
 * Describes an object that loosely represents some sort of database object, regardless if 
 * the data is actually loaded from a database, a third-party source, or generated on-the-fly.
 * The entity `type` can be thought of as a "table name" where objects of the same type would 
 * be persisted.
 *
 * Each entity must provide a `clientId` that uniquely identifies the object when compared
 * to other objects of the same `type`. Ultimately, the unique-entity-identifier is derived
 * by concatenating the `type` with the `clientId`. All `clientId` values are coerced to strings.
 *
 * A set of `keyValues` can (optionally) be assigned for the entity. No strict schema is
 * enforced or expected, though generally the same keys are provided per entity type, where
 * appropriate. A value for a key can be any standard data type, such as strings, booleans,
 * objects, arrays, numbers, etc.
 *
 * Finally, RelEntity objects can be related to this Entity via the `relatedTo` property.
 * For example, a "content" Entity may be related to many "taxonomy" RelEntities.
 *
 * @prop {string} type The type of entity/model/object being acted upon.
 * @prop {string} clientId The unique, external identifier for this entity.
 * @prop {object} keyValues A set of key/values containing metadata about the entity.
 * @prop {RelEntity[]} relatedTo An array of objects this entity is related to.
 */
{
  type: 'content',
  clientId: '12331686',
  keyValues: {
    // Variable per type - no strict schema!
    name: 'The Data Download: Actionable Analytics from Airport Wireless Networks',
    contentType: 'Article',
    // ...
  },
  relatedTo: [],
}

/**
 * The `RelEntity` object.
 *
 * This object essentially extends the `Entity` object, but allows additional key/values that describe
 * the relationship, a.k.a. the relationship's `relFields`.
 *
 * @prop {Entity} entity The entity object.
 * @prop {object} relFields A set of key/values containing fields for the relationship.
 */
{
  entity: {
    type: 'section',
    clientId: '6166',
    keyValues: {
      // Variable per type - no strict schema!
      name: 'Airport Tech & Security',
    },
  },
  relFields: { 
    // Variable per type - no strict schema!
    primary: true,
  },
}

/**
 * The `Event` object.
 *
 * An `Event` represents an interaction with an `Entity` object. Literally this is handled by 
 * relating an `action` (verb) to an `Entity`.
 *
 * An action verb can be any string, though it should semantically describe the action being performed.
 * While there are no strict action types, some examples may include 'view', 'scroll', 'comment', 
 * 'click', etc.
 *
 * For example, if the `action` was 'view' and the `entity` type was 'content', the `Event` can be 
 * interpreted as 'A view action was performed on a content item, with an ID of XYZ.'
 *
 * @prop {string} action The action verb, such as 'click' or 'view'.
 * @prop {(Date|string)} createdAt The date the action was taken.
 * @prop {object} data Any free-form data to append to the event, though this isn't often used.
 * @prop {Entity} entity The `Entity` the action was performed on.
 */
{
  action: 'view',
  createdAt: 'Tue, 23 May 2017 16:19:25 GMT',
  data: { },
  entity: {
    type: 'content',
    clientId: '12331686',
    keyValues: {
      // Variable per type - no strict schema!
      name: 'The Data Download: Actionable Analytics from Airport Wireless Networks',
      contentType: 'Article',
      // ...
    },
    relatedTo: [],
  },
}

/**
 * The `Session` object.
 *
 * Describes the current web session, including anonymous visitor data along with any identified user
 * information.
 *
 * @prop {string} id The client-generated UUID of the session.
 * @prop {(Date|string)} createdAt The date when the session was created.
 * @prop {(string|null)} userId The identified user associated with the session.
 * @prop {string} visitorID The client-generated UUID of the visitor.
 */
{
  id: 'dc8b217a-a5b2-42fe-b989-07b2912250eb',
  createdAt: 'Tue, 23 May 2017 15:45:27 GMT',
  userId: '562fb41776384b70200041a7',
  visitorId: '00f573ad-c7b9-4f97-ac72-cac86b8334ee',
}

/**
 * The `Behavior` object.
 *
 * A `Behavior` represents an `Event` that was created/generated by a `Session`, thereby enabling
 * tracking of a user's (anonymous or otherwise) interaction with an `Entity`.
 *
 * @prop {Event} event The behavior event (action + entity).
 * @prop {Session} session The session (visitor/user) that performed the event.
 */
{
  event: {
    action: 'view',
    createdAt: 'Tue, 23 May 2017 16:19:25 GMT',
    data: { },
    entity: {
      type: 'content',
      clientId: '12331686',
      keyValues: {
        // Variable per type - no strict schema!
        name: 'The Data Download: Actionable Analytics from Airport Wireless Networks',
        contentType: 'Article',
        // ...
      },
      relatedTo: [],
    },
  },
  {
    id: 'dc8b217a-a5b2-42fe-b989-07b2912250eb',
    createdAt: 'Tue, 23 May 2017 15:45:27 GMT',
    userId: '562fb41776384b70200041a7',
    visitorId: '00f573ad-c7b9-4f97-ac72-cac86b8334ee',
  }
}

/**
 * A 'complete' `Behavior` object example, with related entities displayed.
 *
 * In English:
 * Represents that UserID `562fb41776384b70200041a7` viewed the article entitled 
 * "The Data Download: Actionable Analytics from Airport Wireless Networks" which is has a primary
 * section of "Airport Tech & Security" and is tagged to "Homeland Security" and "Perimeter
 * Security."
 *
 * Due to `RelEntity` objects being present, this payload actually creates four events for the user:
 * 1. A content view.
 * 2. A section view.
 * 3. Two taxonomy views.
 */
{
  event: {
    action: 'view',
    createdAt: 'Tue, 23 May 2017 16:19:25 GMT',
    data: { },
    entity: {
      type: 'content',
      clientId: '12331686',
      keyValues: {
        // Variable per type - no strict schema!
        name: 'The Data Download: Actionable Analytics from Airport Wireless Networks',
        contentType: 'Article',
        // ...
      },
      // Note the related entities here...
      relatedTo: [
        {
          entity: {
            type: 'section',
            clientId: '6166',
            keyValues: {
              // Variable per type - no strict schema!
              name: 'Airport Tech & Security',
            },
          },
          relFields: { 
            // Variable per type - no strict schema!
            primary: true,
          },
        },
        {
          entity: {
            type: 'taxonomy',
            clientId: '365',
            keyValues: {
              // Variable per type - no strict schema!
              name: 'Homeland Security',
              tagType: 'Topic'
            },
          },
          relFields: {},
        },
        {
          entity: {
            type: 'taxonomy',
            clientId: '5138',
            keyValues: {
              // Variable per type - no strict schema!
              name: 'Perimeter Security',
              tagType: 'Category'
            },
          },
          relFields: {},
        },
      ],
    },
  },
  session: {
    id: 'dc8b217a-a5b2-42fe-b989-07b2912250eb',
    createdAt: 'Tue, 23 May 2017 15:45:27 GMT',
    userId: '562fb41776384b70200041a7',
    visitorId: '00f573ad-c7b9-4f97-ac72-cac86b8334ee',
  }
}

/**
 * In a "simplified" world, we probably only need to send individual Behavior objects,
 * without the direct relationships. For example...
 */
[
  {
    event: {
      action: 'view',
      createdAt: 'Tue, 23 May 2017 16:19:25 GMT',
      entity: {
        type: 'content',
        clientId: '12331686',
        keyValues: {
          name: 'The Data Download: Actionable Analytics from Airport Wireless Networks',
          contentType: 'Article',
        },
      },
    },
    session: { /* ... */ },
  },
  {
    event: {
      action: 'view',
      createdAt: 'Tue, 23 May 2017 16:19:25 GMT',
      entity: {
        type: 'section',
        clientId: '6166',
        keyValues: {
          name: 'Airport Tech & Security',
        },
      },
    },
    session: { /* ... */ },
  },
  {
    event: {
      action: 'view',
      createdAt: 'Tue, 23 May 2017 16:19:25 GMT',
      entity: {
        type: 'taxonomy',
        clientId: '365',
        keyValues: {
          name: 'Homeland Security',
          tagType: 'Topic'
        },
      },
    },
    session: { /* ... */ },
  },
  {
    event: {
      action: 'view',
      createdAt: 'Tue, 23 May 2017 16:19:25 GMT',
      entity: {
        type: 'taxonomy',
        clientId: '5138',
        keyValues: {
          name: 'Perimeter Security',
          tagType: 'Category'
        },
      },
    },
    session: { /* ... */ },
  }
].forEach((behavior) => {
  API.send(behavior);
});


// We are currently sending the following entity types:
const entityTypes = ['page', 'content', 'taxonomy', 'section', 'publication', 'ad', 'ad_request', 'ad_unit', 'navigation'];