Follow entities

The Follow entities feature lets viewers follow and unfollow entities (players, teams, properties/competitions) directly within the Blaze SDK player experience. Follow state is persisted on-device automatically, and — once activity sync is enabled and the viewer is identified — synced across the viewer's devices through Blaze.

Unlike iOS and Android, the Web SDK doesn't expose an imperative follow-entities manager to your app — the follow button component and the Initialize option below are the only two touchpoints.

Table of contents

• Persistence & sync
  • Out of the box
  • Syncing across devices
• Integration
  • Enabling the follow button
  • Seeding or replacing followed entities
  • Handling follow/unfollow clicks
• Data models
• Best practices
• Troubleshooting
• Support

Persistence & sync

Out of the box

Every follow/unfollow — from a tap on the follow button — is written to local storage on the device immediately. This happens for every viewer, including anonymous ones, survives page reloads, and works fully offline. No backend and no extra setup are required for this baseline behavior.

Syncing across devices

If your app has activity sync enabled and the viewer is identified (externalUserId set), those local changes also sync to Blaze and back — the same gate and pipeline used for the SDK's other user-activity signals. There's no separate follow-specific flag.

Sync is not real-time: it rides the SDK's normal periodic batch/refresh cycle, not an immediate push on every tap. A follow made on one device typically appears on another after the next sync cycle on each side, not instantly.

📘

Your app is no longer required to persist follow state itself or re-seed the SDK on every load. followedEntities (below) is for apps that want to seed from their own backend, mirror state in their own UI, or manage follow state independent of Blaze's sync — not a requirement for basic persistence.

Integration

Enabling the follow button

Add the addFollowButton action handler to your widget or player configuration:

actionHandlers: [
  {
    actionId: 'addFollowButton',
    options: {
      onClick: (e, data) => {
        // Optional — see "Handling follow/unfollow clicks" below
      },
    },
  },
],

That's sufficient for follow state to persist locally and, once activity sync is on, sync across the viewer's devices — no additional code required.

Seeding or replacing followed entities

followedEntities is a Web SDK Initialize option:

BlazeSDK.Initialize('<API-KEY>', {
  externalUserId: 'user-123',
  followedEntities: [
    'player-123',
    'team-123',
    { entityId: 'property-123', providerName: 'stats-perform' }, // providerName is optional
  ],
})

A bare string is shorthand for { entityId } with no provider name.

❗️

followedEntities replaces the viewer's entire followed list — locally and, once synced, for the viewer across every device, latest-wins. On Web this option is evaluated on every Initialize call, so if your integration calls Initialize with a hardcoded or stale followedEntities list on every page load, you will silently erase follows made on other devices (or in the same session) each time. Only pass followedEntities when you deliberately mean "this is the viewer's complete, correct list right now" — omit the option entirely on loads where you don't have a fresh, authoritative list to seed.

Handling follow/unfollow clicks

Implement onClick on the addFollowButton action handler only if you need the event for your own purposes — it's not required for persistence or sync:

{
  actionId: 'addFollowButton',
  options: {
    onClick: (e, data) => {
      console.log(data.sourceId,
                  data.sourceContentType,
                  data.newFollowingState,
                  data.followEntity.entityType,
                  data.followEntity.entityId,
                  data.followEntity.providerName); // optional, opaque data-provider name
    },
  },
},

The internal follow state is already updated by the time this callback fires, so newFollowingState reflects the state after the click.

Data models

FollowedEntityInput

The shape accepted by Initialize({ followedEntities }):

type FollowedEntityInput = string | {
  entityId: string;
  providerName?: string;
};

A bare string is shorthand for { entityId } (no provider name).

BlazeFollowEntity (content-embedded)

The shape passed to your onClick callback's data.followEntity — represents the followable entity embedded in the content that was on screen when the viewer tapped:

type BlazeFollowEntity = {
  entityId: string;
  entityType: 'Player' | 'Team' | 'Property';
  providerName?: string;
  storageFile: { url: string; fileSize: number | null };
};

entityType determines which entity a Moment's follow button shows when multiple are available — it's unrelated to providerName, which is an opaque, unvalidated string naming the data provider that sourced the entity (e.g. "stats-perform"), forwarded to User Activity when the signal syncs.

Best practices

1. Don't call Initialize with followedEntities on every page load unless you genuinely have a fresh, authoritative list — see the warning above. If you don't need to seed/override, omit the option.
2. There's no imperative insert/remove/read API on Web. Unlike iOS/Android, your app can't add or remove a single followed entity outside of a button tap, and can't query the current followed set. If you need that level of control, the follow button tap and the followedEntities replace option are your only two levers.
3. Treat the onClick callback as optional telemetry, not a required integration step — the SDK's own persistence and sync don't depend on it.

Troubleshooting

Follow button not appearing

• Ensure the addFollowButton action handler is registered in your widget/player configuration
• Verify the content has follow entities in the response (followEntities on the content object)

Follows disappearing across page loads

• Check whether Initialize is being called with a stale or empty followedEntities list on load — see the replace warning above

Support

For additional support or questions about the Follow entities feature, please contact the Blaze SDK team or refer to the main SDK documentation.