What You Can Build

The APIs available allow you to import and capture data and port it into Umbel, For example, you can send events, tag segments, and submit longterm Facebook tokens.

Sending Events

To send events to Umbel you must format your data as a JSON object in the schema detailed below. This data must then be POSTed to our API endpoint: https://.capture.umbel.com/v1/event/

API Schema for Events

It is important to note the API event schema:

{
  "api_key": "xxxxxxxxxxxxxxx",
  "events": [
    {
      "umbel_id": <UUID>,
      "name": <string>,
      "value": <string>, or <array>, or <json object>
      "timestamp": <timestamp>,
      "unique": <integer>
    }
  ]
}

The body of the POST you send to Umbel should be in JSON format. Requests are limited to 200 events per post. Each event post is a json object with multiple event objects in the “events”: array.

NOTE: You can bundle multiple events from multiple user sessions in one post up to 200.

Event Glossary:

Tagging Segments

The action.tag event type is used to define segments within your audience based on tags you create that allow Umbel to report on user interactions (i.e. clicks, downloads, form submissions, video plays, etc.) across your site. Tags are used to append extra metadata to a user’s profile, which is later used to segment and filter your audience.

To help get you started, the Umbel team will send you three to five suggested starter tags for you to use. The following chart provides examples of several Umbel Event Tags and how they are used.

Events List

Event Tag Name What the Event Does Example Values
action.tag Segments session data per profile. [“homepage”] or [“sports”, ‘’NFL”]
profile.unique_id (Optional) Supports cross domains. A unique string per user
profile.zip (Optional) Geographically segment data. 78701
profile.address (Optional) Send address data. Each field is optional. You can send all values or one. {“street”: “123main”, “street2”: “suite111”, “city”: “Austin”, “state”: “TX”, “postal_code”: “78701”, “country”: “US” }
profile.birth_year (Optional) Metadata stored on a per user basis. 2011
profile.gender (Optional) Metadata stored on a per user basis. M or F
profile.email (Optional) Only stored if different from Facebook email. test@umbel.com
profile.facebook_access_token Used to gather social data. AAADSxG9Y4yABAJzqAQuCmBZ..
profile.twitter_user_id Used to gather social data. 42668969
profile.linkedin_access_token If you have the access token, send it to gather social data. {‘linkedin_access_token’: }
profile.linkedin_access_token If you have an authorization code, send api_key and secret to gather social data. oauth_token_secret=890sfds4…&oauth_token=84sfe…

Example Profile Events

The following samples shows

{
  "api_key": "xxxxxxxxxxxxxxx",
  "events": [
    {
      "umbel_id": "5b094555-5295-4655-a023-5375102ab338",
      "name": "profile.facebook_access_token",
      "value": "AAADRDxIGgD0BAJyhDW1Pl3SiTVskurijoHa1OrDcfputMLOY61wvXXXFMbZ",
      "timestamp": "2012-05-15T15:16:03.039-0500",
      "unique": 0
    },
    {
      "umbel_id": "5b094555-5295-4655-a023-5375102ab338",
      "name": "profile.linkedin_access_token",
      "value": "AE24324JKLIFS987879",
      "timestamp": "2012-05-15T15:16:03.039-0500",
      "unique": 1
    },
    {
      "umbel_id": "5b094555-5295-4655-a023-5375102ab338",
      "name": "profile.email",
      "value": "example@example.com",
      "timestamp": "2012-05-15T15:16:03.039-0500",
      "unique": 2
    },
    {
      "umbel_id": "5b094555-5295-4655-a023-5375102ab338",
      "name": "profile.zip",
      "value": "78701",
      "timestamp": "2012-05-15T15:16:03.039-0500",
      "unique": 3
    },
    {
      "umbel_id": "5b094555-5295-4655-a023-5375102ab338",
      "name": "profile.birth_year",
      "value": "2011",
      "timestamp": "2012-05-15T15:16:03.039-0500",
      "unique": 4
    },
    {
      "umbel_id": "5b094555-5295-4655-a023-5375102ab338",
      "name": "profile.gender",
      "value": "M",
      "timestamp": "2012-05-15T15:16:03.039-0500",
      "unique": 5
    }
  ]
}

Tag Hierarchy

Tag names can be structured to represent and organize the engagement behaviors from your site. You will need to track engagement metrics specific to your property, and the action.tag allows for the creation of unique structured segments. For example, a concert ticketing site may wish to measure tickets sold and band engagement level.

These following two tags could track those events:

{
  "api_key": "xxxxxxxxxxxxxxx",
  "events": [
    {
      "umbel_id": "5b094555-5295-4655-a023-5375102ab338",
      "name": "action.tag",
      "value": ["Bands", "U2"],
      "timestamp": "2012-05-15T15:16:03.039-0500",
      "unique": 0
    },
    {
      "umbel_id": "5b094555-5295-4655-a023-5375102ab338",
      "name": "action.tag",
      "value": ["Tickets", "VIP"],
      "timestamp": "2012-05-15T15:21:10.045-0500",
      "unique": 1
    }
  ]
}

Sending Long-Lived Facebook Tokens to Umbel

When sending the long-lived token to Umbel from your server, you will need to include the user’s umbel_id, generated by the Umbel JavaScript SDK to associate with the user’s profile. This ID is a UUID stored in a cookie called umbel_browser_id. For information on how to convert short-lived tokens to long-lived tokens, refer to Facebook Token Reference for How to Convert Short-Lived Facebook Tokens to Long-Lived Tokens.

A sample Post in JSON format:

{
  "api_key": "xxxxxxxxxxxxxxx",
  "events": [
    {
      "umbel_id": “<UUID>”, //from javascript cookie
      "name": "profile.facebook_access_token",
      "value": "RBuDIi3HK0B6fZC69ZBhSU9ROLtSR",
      "timestamp": "2012-05-15T15:16:03.039-0500",
      "unique": 0
    }
  ]
}

To enable test mode append this optional parameter: “testing”: true

Note: The Facebook Authentication section of this guide contains further documentation and information on other options to deliver your Facebook tokens.

Facebook Token Reference

The Append process:

During the user’s Facebook registration process with your site/app an Authentication token is generated. You will then deliver that token to Umbel via our API or native SDKs. Umbel will first verify the token type short or long lived.

Short-Lived token process:

If the token is a short lived token generated from the Facebook JavaScript SDK then it will expire in 2 hours. Umbel fast tracks these events in a priority queue to convert them into long lived tokens (60 day expiration). To facilitate this conversion you must provide your Facebook app_id and secret in your Umbel property configuration.

Long-Lived tokens are then stored with each user profile and interrogated via the Facebook Graph API. The the resulting user’s: birthday, friend count, location, and likes are then appended the profile. The Facebook email is also appended to the user profile and Umbel attempts to de-dupe and merge any existing profiles with a matching email or Facebook ID. The email address is then queued up for further appends with Acxiom.

Token refresh occurs weekly where Umbel will re-interrogate the Facebook Graph API and appending new information to the user’s profile.

Resources for How to Convert Short-Lived Facebook Tokens to Long-Lived

There are two ways you can choose to implement Facebook Login on your site: Server-Side and Client-Side.

Server-Side login flow is the most secure way to authenticate users and provides access to long-lived tokens. Client-Side login flow provides short-lived tokens which much be converted to long-lived tokens in order to maximize the value of your users’ social data. You can find more information on how to extend tokens on the Facebook Developer Website:

Facebook Developers: Login for Server-side Apps

Facebook Developers: Extending Access Tokens

Facebook Developers: Token Debugger

SDKs

Umbel provides SDKs (Software Development Kits) that, when added to your digital properties, send data to Umbel. While your team members could write custom code themselves, our SDKs are provided to do the heavy lifting. The Umbel JavaScript SDK is most commonly used on websites, including mobile versions of websites, to send data to Umbel. We also provide iOS and Android SDKs for use within native mobile applications.