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 calledumbel_browser_id. For information on how to convert short-lived tokens to long-lived tokens, see Resources 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.

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.