experience-engine-sdk

Create awesome experiences for your audience in seconds!

This is the experience-engine core. It is broken up into common parts. You can include just the part you need, or the whole thing by importing common.

Activations

"Activations" are related stuff that is associated with the parent content (i.e. the movie you're watching or the music you're listening to).

The activations format is a way of managing all the complexities associated with dealing with all the related content:

• Who should it appear for? (the experience service narrows this down)
• What should be displayed? (person, place, music, product, etc)
• When should it be available? (i.e. the time within the media to display it)
• Where should it go? (i.e. the top, the left, a hidden channel, etc)
• Why is it being shown? (i.e. the instance that was merged)
• How should it be displayed? (i.e. the template that draws it)

Activations can be "activated" or "queried", i.e. providing what/when/where.

If you ask for active activations, you'll get back a renderable list. If you query activations, you'll also get back instances that match.

Understanding the format

  {
    "id": "uuid",
    "settings": {
        "text": "Hello"
    },
    "instances": [
      { "when": { "start": 1, "end": 15.7 }, "active": true },
    ]
  },

We've spent years trying to make the data format as simple as possible. We've been able to cut complexity in half multiple times and feel we're at a place that is incredibly simplistic, yet more flexible than we even thought possible.

Generally, there are only 3 sections...

ID

The id is a UUID and only there to keep track of where the source data came from. It will be generated for you and you can completely ignore it.

Settings

Settings behave exactly like content settings and use the same merge behaviors. Settings contain absolutely everything that is used to render the activation.

Instances

Sometimes you want to reference the same thing more than once in the same content; for example if a certain actor is on the screen multiple times, or if the same location in a film appears many times. Instances let you do that.

An instance of an activation also behaves exactly like settings; in fact, when an "active" query is made on media and a match is found on an instance, that instances object is simply merged into settings so it can be rendered.

An activation example...

  {
    "id": "4cd42cd5-e3bf-4d16-a5ab-b834c8f4a1d9",
    "settings": {
      "reference": "@activation:3f001fb3-15d0-40f2-b22c-0bb9f01928a8",
      "icon": 'https://upload.wikimedia.org/wikipedia/commons/thumb/3/33/Tom_Cruise_by_Gage_Skidmore_2.jpg/476px-Tom_Cruise_by_Gage_Skidmore_2.jpg',
      "details": {
        "character": {
          "name": "Pete \"maverick\" Mitchell"
        }
      }
    },
    "instances": [
      { "when": { "start": 1, "end": 15.7 }, "screen": { "top": 0.21, "left": 0.1, "width": 0.5, "height": 0.3 }, "details": "character": { "mood": "happy" }} },
      { "when": { "start": 112.3, "length": 7.22 }, "details": { "character": { "mood": "angry", "action": "jumping" } },
      { "when": { "start": 233, "length": 10 }, "where": "top", "active": true, "what": "trivia", "text": "@triviaText:details.birthplace" },
    ]
  },

...The above shows:

1. A reference to another activation (in this case Tom Cruise), which will import all the current details about this person ahead of time using the experience service. You don't have to maintain it in your content itself.
2. Modifications to the icon for the activation (showing a specific image chosen by the content creator, and naming the actors charicter in this content)
3. Three instances of this activation, including:

• 1-15.7 seconds, on the top left of the screen, the character is visible and in a happy mood.
• Just under 2 minutes in, for 7.22 seconds, the character is angry and performing a "jumping" action.
• At about 4 minutes in, for 10 seconds, some trivia is shown to the person explaining where this actor was born.

Generating activations: It's worth noting that the text for the trivia came from a plugin called "triviaText", which was told to generate the trivia from the activation's birthplace details field, which amounts to something like: "Did you know? Tom Cruise was born in Syracuse, New York". The injection of the time, the length, where to place it, the decision to add trivia, and to add it about the person's birthplace, came from another plugin, called "@relevantTriviaGenerator, which uses details about when this instance is on screen, what the liklihood the audience will want to know the trivia is, and other factors; no human needed to add it.

Making use of activations

You can get a list of what is active at any time with $common.activations.active(Activations, Query), where Activations is the list of activations you want to query, and Query is a query object, explained next.

Querying with the Query object

The query object is pretty simple. It not only searches the activation settings, it searches all instances too...

{
  "what": "person", // Filter for any text that matches the things you're interested in.
  "when": 100 // The time in seconds you want to look at.
  "where": "top-left", // Filter for any location the activation is meant to be drawn in.
}

Some examples...

Everything visible at 10.4 seconds... $common.activations.active(Activations, { when: 10.4 })

Everything available (not just visible, i.e. this would include scene data, and all related instances as well) at 10.4 seconds... $common.activations.query(Activations, { when: 10.4 })

Everything that appears in the "right" location... $common.activations.query(Activations, { where: 'right' })

Everything that appears in the "top-right", "right", and "bottom-right" location... $common.activations.query(Activations, { where: 'top-right', 'right', 'bottom-right' })

Everything visible in the "right" location at 22 seconds, that is also a person... $common.activations.active(Activations, { where: 'right', what: 'person', when: 22 })

Get a list of all locations and related data... $common.activations.query(Activations, { what: 'place' })