Custom Data Options

Guide on passing custom data to Gumlet Insights SDKs

Gumlet Insights lets you attach first-party metadata when you initialise the SDK (or update it later). Fields listed below are stored on modern v2 ingest and appear as dashboard breakdowns.

All examples use the current web SDK (GumletInsights + attach). The same config keys work with React Native (withGumletInsights config prop) and other player integrations.

Required field

Every config must include workspace_id from Workspaces. Without it, the license check fails and no events are sent.

Supported fields (Insights v2)

These are the custom / first-party fields the current analytics pipeline persists and exposes for filtering and breakdowns.

User

Parameter	Data Type	Beacon / column	Description
`userId`	String	`custom_user_id`	Unique ID for the user in your product database.
`userEMail`	String	`user_email` / `custom_user_email`	Email the user signed up with. (`userEmail` is accepted as an alias.)

Video

Parameter	Data Type	Beacon / column	Description
`customVideoId`	String	`custom_video_id`	Your internal video ID (e.g. database primary key).
`customVideoTitle`	String	`custom_video_title`	Title of the video.

Additional slots

Five free-form string slots. Keep each slot’s meaning consistent across your product.

Parameter	Data Type	Beacon / column
`customData1`	String	`custom_data_1`
`customData2`	String	`custom_data_2`
`customData3`	String	`custom_data_3`
`customData4`	String	`custom_data_4`
`customData5`	String	`custom_data_5`

Keep the definition of each customDataN slot the same for every integration that reports into the same workspace.

Not supported on Insights v2

The following keys still exist on some older SDK type definitions or v1 pipelines, but they are not stored or breakable on the current v2 Insights tables / dashboard. Do not rely on them:

Category	Unsupported keys
User	`userName`, `userPhone`, `userProfileImage`, `userAddressLine1`, `userAddressLine2`, `userCity`, `userState`, `userCountry`, `userZipcode`
Video	`customContentType`, `customVideoDurationMillis`, `customEncodingVariant`, `customVideoLanguage`, `customVideoSeries`, `customVideoProducer`, `customVideoVariant`, `customVideoVariantName`
Player labels	`customPlayerIntegrationVersion`, `customPlayerName`, `customPageType`
Extra slots	`customData6`, `customData7`, `customData8`, `customData9`, `customData10`

Player software name and version (player_software, player_software_version) are filled automatically by the SDK / adapter — you do not set them via custom player labels.

Pass data on init

const gumletConfig = {
  workspace_id: 'YOUR_WORKSPACE_ID', // required
  userId: '123',
  userEMail: 'oceane.bourgeois@example.com',
  customVideoId: 'HIMYMSeason1Episode1',
  customVideoTitle: 'Pilot',
  customData1: 'campaign-a',
  customData2: 'variant-b',
  customData3: '',
  customData4: '',
  customData5: '',
};

const gumletInsights = new gumlet.GumletInsights(gumletConfig);
await gumletInsights.attach(player); // HTMLVideoElement / HLS.js / Shaka / etc.

For browser pages, load the SDK from the CDN first:

<script type="module" src="https://cdn.gumlytics.com/insights/4.0/main.mjs"></script>

Update data after init

Use these when the viewer logs in later, or the same player instance starts a different title.

Update helpers clear omitted fields

For each helper below, fields you omit from the object are cleared. Re-pass any value that should stay set.

User

gumletInsights.updateCustomUserData({
  userId: '123',
  userEMail: 'christelle.robert@example.com',
});

Video

gumletInsights.updateCustomVideoData({
  customVideoId: 'HIMYMSeason1Episode2',
  customVideoTitle: 'Episode 2',
});

Additional slots

gumletInsights.updateCustomData({
  customData1: 'campaign-b',
  customData2: 'variant-c',
  customData3: '',
  customData4: '',
  customData5: '',
});

React Native

The same supported keys go on the config prop of withGumletInsights(Video):

<TrackedVideo
  config={{
    workspace_id: 'YOUR_WORKSPACE_ID',
    userId: '123',
    userEMail: 'viewer@example.com',
    customVideoId: 'episode-1',
    customVideoTitle: 'Pilot',
    customData1: 'campaign-a',
  }}
  source={{ uri: 'https://example.com/stream.m3u8' }}
  paused={paused}
/>

See React Native Player and the sample app.

Parameter reference

Complete list of custom data parameters available on Insights v2:

Parameter	Category	Data Type	Beacon / column	Update helper
`userId`	User	String	`custom_user_id`	`updateCustomUserData()`
`userEMail`	User	String	`user_email` / `custom_user_email`	`updateCustomUserData()`
`userEmail`	User	String	Same as `userEMail` (alias)	`updateCustomUserData()`
`customVideoId`	Video	String	`custom_video_id`	`updateCustomVideoData()`
`customVideoTitle`	Video	String	`custom_video_title`	`updateCustomVideoData()`
`customData1`	Additional	String	`custom_data_1`	`updateCustomData()`
`customData2`	Additional	String	`custom_data_2`	`updateCustomData()`
`customData3`	Additional	String	`custom_data_3`	`updateCustomData()`
`customData4`	Additional	String	`custom_data_4`	`updateCustomData()`
`customData5`	Additional	String	`custom_data_5`	`updateCustomData()`

workspace_id is required for the SDK but is a workspace identifier, not a custom-data field.

AVPlayer (iOS)

Getting Started