Analytics

The SDK automatically collects playback and engagement events the moment the feed is displayed. No setup is required. Events are batched and delivered in the background. If the app is terminated before a batch is sent, events are persisted to disk and retried on the next launch. The SDK collects metrics for every video view. A view session starts when a content item becomes active in the feed and ends when the user swipes away, the feed leaves the screen, or the app backgrounds.

Engagement

Metric	Type	Description
`watchTimeMs`	`Int`	Wall-clock time from view start to end (ms). Includes time spent buffering and paused.
`playingTimeMs`	`Int`	Actual playing time accumulated at 1 Hz (ms). Excludes buffering and pauses.
`videoStartupTimeMs`	`Int?`	Time from impression to player ready (ms). Nil if the player never started.
`exitBeforeStart`	`Bool`	`true` if the user swiped away before playback began.
`completed`	`Bool`	`true` if the video played to its natural end at least once.
`loopCount`	`Int`	Total number of completions. 0 if the video never reached the end.

Quality of experience

Metric	Type	Description
`rebufferCount`	`Int`	Number of rebuffering stalls during playback.
`rebufferDurationMs`	`Int`	Total time spent rebuffering (ms).
`seekCount`	`Int`	Number of user-initiated seek operations.
`seekDurationMs`	`Int`	Total time spent seeking (ms).
`avgBitrateBps`	`Int?`	Weighted average playback bitrate (bits per second). Nil if no samples collected.
`renditionChangeCount`	`Int`	Total HLS rendition (quality) switches.
`renditionUpshiftCount`	`Int`	Switches to a higher-quality rendition.
`renditionDownshiftCount`	`Int`	Switches to a lower-quality rendition.

Fallback playback

Metric	Type	Description
`reason`	`String`	Why the fallback activated: `player_failed` (HLS error during playback), `proactive_next_slot` (HLS error detected on prefetched next video), or `no_primary_url` (primary streaming URL was empty or invalid).
`primaryUrl`	`String`	The original HLS streaming URL that failed.
`fallbackUrl`	`String`	The static MP4 URL the SDK switched to.

Emitted as a playbackFallback event once per fallback activation. Only fires when a fallback URL was provided via FeedInput. When this event fires, the player does not enter the error state — it resumes playback from the fallback URL.

Feed session

Metric	Type	Description
`totalSessionTime`	`Double`	Total time the feed was on screen (seconds).
`videosWatched`	`Int`	Number of videos the user viewed during the session.

Metric	Type	Description
`filled`	`Bool`	Whether the ad request returned a creative.
`errorReason`	`String?`	Failure reason if the ad was not filled (`no_fill`, `timeout`, `network_error`, `provider_error`).
`quartile`	`String`	Playback milestone reached (`first_quartile`, `midpoint`, `third_quartile`, `complete`).
`watchTime`	`Double`	Watch time before the user skipped the ad (seconds).

Context

Collected once per view and attached automatically.

Metric	Type	Description
`captionsEnabled`	`Bool`	Whether captions were enabled during the view.
`deviceInfo`	`Object`	Device and connection metadata: OS, device model, connection type. Includes `osName`, `osVersion`, `deviceCategory`, `deviceManufacturer`, `deviceModel`, `connectionType`.
`clientAppName`	`String?`	App name passed at SDK init.
`clientAppVersion`	`String?`	App version passed at SDK init.
`customDimensions`	`Object?`	Custom dimensions (`custom_1` through `custom_5`), if set at init.

All of these metrics are queryable through the metrics API, which supports aggregation, dimension breakdowns, timeseries, filtering, and raw data export.

Custom dimensions

Pass up to 5 string dimensions at SDK init. They attach to every viewEnd event and become queryable as dimensions in the metrics API.

Swift
Kotlin
Flutter
React Native
Web

let shortKit = ShortKit(
    apiKey: "pk_live_...",
    config: FeedConfig(),
    clientAppName: "MyNewsApp",
    clientAppVersion: "2.1.0",
    customDimensions: [
        "custom_1": "sports",
        "custom_2": "premium_user",
        "custom_3": "experiment_hero_v2"
    ]
)

val shortKit = ShortKit(
    apiKey = "pk_live_...",
    config = FeedConfig(),
    clientAppName = "MyNewsApp",
    clientAppVersion = "2.1.0",
    customDimensions = mapOf(
        "custom_1" to "sports",
        "custom_2" to "premium_user",
        "custom_3" to "experiment_hero_v2"
    )
)

ShortKitProvider.apiKey(
  apiKey: 'pk_live_...',
  clientAppName: 'MyNewsApp',
  clientAppVersion: '2.1.0',
  customDimensions: {
    'custom_1': 'sports',
    'custom_2': 'premium_user',
    'custom_3': 'experiment_hero_v2',
  },
  child: MyApp(),
)

import { ShortKitProvider, ShortKitFeed } from '@shortkitsdk/react-native';

function App() {
  return (
    <ShortKitProvider
      apiKey="pk_live_..."
      config={{}}
      clientAppName="MyNewsApp"
      clientAppVersion="2.1.0"
      customDimensions={{
        custom_1: 'sports',
        custom_2: 'premium_user',
        custom_3: 'experiment_hero_v2',
      }}
    >
      <ShortKitFeed />
    </ShortKitProvider>
  );
}

const sk = new ShortKit({
  apiKey: 'pk_live_...',
  clientAppName: 'MyNewsApp',
  customDimensions: {
    custom_1: 'sports',
    custom_2: 'premium_user',
    custom_3: 'experiment_hero_v2',
  },
});

Keys must be custom_1 through custom_5. Other keys are silently dropped. Values are plain strings. Custom dimensions are immutable after init. To change them (for example, after a user upgrades their subscription), create a new ShortKit instance. clientAppName and clientAppVersion are also set at init and included in every viewEnd event. Use them to segment analytics by app version.

Content signals

contentSignal is the only event you trigger manually. Use it to send positive or negative signals back to the recommendation engine.

Swift
Kotlin
Flutter
React Native
Web

shortKit.player.sendContentSignal(.positive)
shortKit.player.sendContentSignal(.negative)

shortKit.player.sendContentSignal(ContentSignal.POSITIVE)
shortKit.player.sendContentSignal(ContentSignal.NEGATIVE)

final controller = ShortKit.of(context);

// Positive signal (e.g. thumbs up)
controller.sendContentSignal('positive');

// Negative signal (e.g. thumbs down)
controller.sendContentSignal('negative');

import { useShortKitPlayer } from '@shortkitsdk/react-native';

function SignalButtons() {
  const { sendContentSignal } = useShortKitPlayer();

  return (
    <>
      <Button title="Like" onPress={() => sendContentSignal('positive')} />
      <Button title="Dislike" onPress={() => sendContentSignal('negative')} />
    </>
  );
}

sk.player.sendContentSignal('positive');
sk.player.sendContentSignal('negative');

The signal is emitted with the contentId of the currently active video.

User identity

The SDK generates a persistent anonymous UUID by default. This ID is included in every event and used as the viewer_id dimension in analytics. Call setUserId() to switch to identified mode. This links the anonymous device ID to your known user ID for identity resolution.

Swift
Kotlin
Flutter
React Native
Web

// Associate events with a known user
shortKit.setUserId("user_12345")

// Revert to anonymous tracking (generates a new anonymous ID)
shortKit.clearUserId()

shortKit.setUserId("user_12345")
shortKit.clearUserId()

final controller = ShortKit.of(context);

// Associate events with a known user
controller.setUserId('user_12345');

// Revert to anonymous tracking
controller.clearUserId();

import { useShortKit } from '@shortkitsdk/react-native';

function IdentityManager() {
  const { setUserId, clearUserId } = useShortKit();

  // Associate events with a known user
  setUserId('user_12345');

  // Revert to anonymous tracking
  clearUserId();
}

// Associate events with a known user
sk.setUserId('user_12345');

// Revert to anonymous tracking
sk.clearUserId();

Querying analytics data

Use the metrics API to query aggregate engagement data, break down by dimensions, chart timeseries, and export raw view records. See Metrics Overview for the full list of metrics and dimensions, plus the Events API for raw event data.

Get Started

Content

Display

Build Your Experience

Users & Data

Engagement

Quality of experience

Fallback playback

Feed session

Ads

Context

Custom dimensions

Content signals

User identity

Querying analytics data

​Engagement

​Quality of experience

​Fallback playback

​Feed session

​Ads

​Context

​Custom dimensions

​Content signals

​User identity

​Querying analytics data

Engagement

Quality of experience

Fallback playback

Feed session

Ads

Context

Custom dimensions

Content signals

User identity

Querying analytics data