Customer.io
v1.0.0
OpenAPI 3.1.0

Pipelines API - Video Events

Video Semantic Events

This document describes semantic events for video tracking in the Customer.io Pipelines API.

Semantic events are special payloads for our track endpoint based on the event name. When you send a video event with a specific name (like Video Playback Started), Customer.io and downstream integrations recognize it and handle it appropriately.

With semantic events, you can set up your events and they'll work with any of our destinations that support video events.

Server addresses: US and EU

Customer.io hosts services in the United States (US) and European Union. Select the appropriate server address for your region.

Region Server Address
US https://cdp.customer.io
EU https://cdp-eu.customer.io

If you're in our EU region, you'll need to specify the EU URL when you initialize our server-side libraries.

Authentication

Use a private key (sk_) as a bearer token: Authorization: Bearer sk_us_.... To get one, set up the Customer.io API integration. In a browser or mobile app, use a public key (pk_). Learn more about public and private keys.

Legacy credentials: If you already have a Customer.io API integration with a write key, you can keep using it with Basic authentication: the key is the Username, and the Password is blank.

US region

Client Libraries
Shell Curl

Track Video Event

​

Send video events to track playback, content, and ad interactions.

Video semantic events follow a standard structure for video analytics across different platforms.

Headers
  • X-Strict-Mode
    enum
    const:  
    1

    When set to 1, enables strict validation that returns proper HTTP error codes (400/401) for validation failures. When not set or set to any other value, the API operates in permissive mode, logging errors but returning HTTP 200.

    values
    • 1
Body
required
application/json
      • event
        enum
        const:  
        Video Playback Started
        required

        The event name. Must be Video Playback Started for this semantic event.

        values
        • Video Playback Started
      • properties
        Type: object
        required

        Properties describing content assets for Video Playback Started events.

        • ad_asset_id
        • ad_enabled
          Type: boolean

          Set to true if a viewer can see your ads. You'd set false if a viewer has ad block or other blockers enabled.

        • ad_pod_id
        • ad_type
          Type: string enum

          The type of ad playing at the time of the event. Values can include pre-roll, mid-roll, and post-roll.

          values
          • pre-roll
          • mid-roll
          • post-roll
        • bitrate
          Type: integer

          The current kbps.

        • content_asset_ids
          Type: array string[]

          The ID of the videos a user started. The array indicates a potential playlist of videos/content IDs a person is starting.

        • content_pod_ids
          Type: array string[]

          The IDs of the content "pods" in a playback session. Imagine a video that contains content and an ad; that means the video contains two pods—one for the content and one for the ad. The array indicates a potential playlist of content pod IDs a person is starting.

        • framerate
          Type: integer

          The average frames per second (fps).

        • full_screen
          Type: boolean

          If true, playback is in fullscreen mode.

        • livestream
          Type: boolean

          Set to true if the playback is a livestream.

        • position
          Type: integer

          The current index position in seconds of the playhead, including the duration of any ads seen (if available). If the playback is a livestream, check the documentation for relevant destinations for details on how to correctly pass the playhead position.

        • quality
          Type: string

          The video quality of playback, like 480p or highres.

        • session_id
          Type: string

          The unique ID of the overall session used to tie all events generated from a specific playback. This value should be the same across all playback, content, and ad events if they are from the same playback session.

        • sound
          Type: integer
          min:  
          0
          max:  
          100

          The current volume of the video player as a value between 1 and 100.

        • total_length
          Type: integer

          The total duration of the playback in seconds. This should include the duration of all your content and ad included in this playback session. For livestream playback, send null.

        • video_player
          Type: string

          The name of the video player the client uses, like youtube or vimeo.

        • propertyName
          Type: anything

          Additional custom properties for the event.

      • type
        enum
        const:  
        track
        required

        The event type. Must be track for event calls.

        values
        • track
      • userId
        Type: string
        required

        The unique identifier for the user.

      • context
        Type: object · Context

        Additional context about the event, such as device information, IP address, user agent, etc. Most of our libraries collect this automatically.

      • integrations
        Type: object · Integrations

        Control which integrations receive this event. By default, all enabled integrations receive events.

      • timestamp
        Type: string Format: date-time

        The ISO-8601 timestamp when the event occurred. If not provided, Customer.io records the time when the request is received.

Responses
  • application/json
  • application/json
  • 401

    Unauthorized request. Make sure that you provided the right credentials.

Request Example for post/track
{
  "event": "Video Playback Started",
  "properties": {
    "ad_asset_id": "ad_asset_123",
    "ad_enabled": true,
    "ad_pod_id": "ad_pod_123",
    "ad_type": "pre-roll",
    "bitrate": 5000,
    "content_asset_ids": [
      "video_123",
      "video_456"
    ],
    "content_pod_ids": [
      "pod_123",
      "pod_456"
    ],
    "framerate": 30,
    "full_screen": false,
    "livestream": false,
    "position": 120,
    "quality": "1080p",
    "session_id": "session_abc123",
    "sound": 75,
    "total_length": 3600,
    "video_player": "youtube",
    "additionalProperty": null
  },
  "type": "track",
  "userId": "user_12345",
  "context": {
    "additionalProperty": "anything"
  },
  "integrations": {
    "All": false,
    "Mixpanel": true,
    "Segment": true
  },
  "timestamp": "2024-01-15T10:30:00.000Z"
}

{}

A successful request returns an empty object response.

Models