Platform and authentication

This guide explains how QuickplayPlatformProvider initializes platform services, manages access tokens, and exposes auth-aware playback utilities. Use it when you need to understand provider configuration or custom token flows.

Provider responsibilities

QuickplayPlatformProvider centralizes the service wiring that QuickplayPlayer needs for Quickplay-hosted playback.

• Initializes platform authorization and content authorization clients
• Manages the anonymous access token lifecycle, or requests user tokens from your app-owned provider
• Maintains device identity across sessions
• Exposes provider state through useQuickplayPlatform
• Applies optional analytics session configuration

Configure with remote config

Remote config is the recommended setup. You pass one configUrl, and the provider discovers the required endpoints.

import { QuickplayPlatformProvider } from '@quickplay/player-react';

<QuickplayPlatformProvider
  configUrl="https://api.example.com/config"
  headers={{ 'X-Property-Id': 'property-id' }}
>
  <App />
</QuickplayPlatformProvider>;

With remote config, token initialization is automatic. The provider reads guestFlatURL and uses anonymous access for you.

Configure analytics

Analytics is optional and can be enabled at provider level. The full AnalyticsConfig structure is:

interface AnalyticsConfig {
  enabled: boolean;
  application: {
    name: string;
    version: string;
    build: string;
  };
  device: {
    platformType: PlatformType; // WEB, IOS, ANDROID, etc.
    customDeviceManufacturer?: string;
    customDeviceName?: string;
  };
  user: {
    id: string;
  };
}

import { PlatformType } from '@quickplay/player-react';

<QuickplayPlatformProvider
  configUrl="https://api.example.com/config"
  analyticsConfig={{
    enabled: true,
    application: { name: 'My Video App', version: '1.0.0', build: '1' },
    device: { platformType: PlatformType.WEB },
    user: { id: 'anonymous' },
  }}
>
  <App />
</QuickplayPlatformProvider>;

Understand token management

For the default anonymous flow, the provider caches the guest token, shares concurrent token requests, and refreshes it shortly before it expires. You do not need manual refresh logic.

With remote config, the provider reads the guest token endpoint from guestFlatURL. With manual configuration, set config.anonymousTokenEndpoint instead. The guest endpoint must return this JSON structure, where expires_in is in seconds:

{
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIs...",
    "expires_in": 3600
  }
}

Provide app-owned authentication

Most apps don't need custom authentication. In remote-config mode, the provider uses anonymous access automatically when you omit the authentication props. In manual configuration mode, anonymous access uses config.anonymousTokenEndpoint.

When your app has its own login system, pass a QuickplayAccessTokenProvider. Your app owns user tokens and identity changes. The SDK owns platform and content authorization and device registration. The SDK never clears or logs out your provider.

import type { QuickplayAccessTokenProvider } from '@quickplay/player-react';

const accessTokenProvider: QuickplayAccessTokenProvider = {
  getAccessToken: () => auth.getValidAccessToken(),
  getUserIdentity: () => auth.getQuickplayIdentity(),
  subscribeUserIdentity: listener => auth.subscribeIdentityChanges(listener),
};

<QuickplayPlatformProvider
  configUrl="https://api.example.com/config"
  accessTokenProvider={accessTokenProvider}
>
  <App />
</QuickplayPlatformProvider>;

Here, auth is your app's authentication module. The same prop works with config instead of configUrl.

For manual configuration without a provider, omit all authentication props and set anonymousTokenEndpoint in config.

Follow these rules when you implement the provider:

• getAccessToken must return a nonempty, valid token or reject. Your app handles token refresh and storage. The SDK doesn't fall back to anonymous access when a custom provider fails.
• getUserIdentity returns a QuickplayUserIdentity with a userType of anonymous, registered, subscribed, or a custom string, plus optional userId, profileId, and profileType. Custom user types aren't mapped to an analytics user type.
• subscribeUserIdentity registers a listener and returns an unsubscribe function. Call the listener after login, logout, or profile changes, with a reason of login, logout, profileSwitch, or other. Don't call it for an ordinary token refresh. Fixed identities can return a no-op unsubscribe function.
• Keep the provider instance stable across renders. Use useMemo if you create it inside a component.

When an identity changes, the SDK rebuilds content authorization and device registration, and updates analytics identity metadata without restarting the application session. An identity change doesn't stop or restart a stream that is already playing. Your app decides the playback policy.

To change authentication sources, replace the prop. To return to anonymous access, set the prop to undefined.

Report identity changes to analytics

When analytics is enabled, the reason you pass to the subscribeUserIdentity listener also determines which user event the SDK reports:

Reason	Analytics event
login	LOGIN
logout	LOGOUT
profileSwitch	UPDATE_PROFILE
other	None. User metadata is updated only.

Pass the reason that matches what happened, because analytics reporters receive these events as they are. The identity that getUserIdentity returns at startup updates user metadata but doesn't report an event. If a change happens before analytics finishes initializing, the SDK reports it once analytics is ready.

Log out

The SDK doesn't log out your user, and reset doesn't either. Call your own logout, then do one of the following:

• Notify the listener with a logout reason and the new identity. Your provider must return valid tokens for that identity.
• Set accessTokenProvider to undefined to switch to SDK-managed anonymous access.

The SDK re-registers the device automatically. An active player keeps playing while it re-registers.

Acquire tokens with SDK dependencies

Use createAccessTokenProvider when your app needs platform authorization or device information to issue its user token. The provider calls the factory before device registration and passes it the SDK-owned dependencies.

import type { QuickplayAccessTokenProviderFactory } from '@quickplay/player-react';

const createAccessTokenProvider: QuickplayAccessTokenProviderFactory = ({
  platformClient,
  xClientId,
  getPlatformAccessToken,
}) => ({
  getAccessToken: () =>
    auth.getValidAccessToken({
      deviceId: platformClient.id,
      xClientId,
      getPlatformAccessToken,
    }),
  getUserIdentity: () => auth.getQuickplayIdentity(),
  subscribeUserIdentity: listener => auth.subscribeIdentityChanges(listener),
});

<QuickplayPlatformProvider
  configUrl="https://api.example.com/config"
  createAccessTokenProvider={createAccessTokenProvider}
>
  <App />
</QuickplayPlatformProvider>;

The factory context provides these values:

Field	Description
platformClient	The SDK-owned device client used for registration, including its ID and device capabilities.
xClientId	Client identifier for the X-Client-ID header of your token endpoint.
getPlatformAccessToken	Returns only the client-credentials platform token, without requesting a user token.

caution

Keep the factory stable across renders. Return the provider synchronously and do async work inside getAccessToken. The provider can run the factory again on reset, configuration changes, or React Strict Mode setup, so don't start logins, network requests, or subscriptions during construction. Don't use AuthorizationUtil.makeAuthorizedRequest inside getAccessToken to acquire the same user token, because it can recurse. Token getters from a replaced factory context reject.

Supply exactly one of accessTokenProvider, createAccessTokenProvider, or the legacy quickplayAccessTokenManager. The provider rejects multiple authentication sources.

Migrate from a token manager

QuickplayAccessTokenManager and the quickplayAccessTokenManager prop are deprecated but still work. Migrate to accessTokenProvider or createAccessTokenProvider.

• Remove setPlatformDependencies. Use the factory context instead. Only legacy managers receive setPlatformDependencies.
• Remove clear. The SDK no longer calls it. If your app relied on clear for logout, call your logout explicitly.
• Add getUserIdentity and subscribeUserIdentity.

// Before
<QuickplayPlatformProvider
  configUrl={configUrl}
  quickplayAccessTokenManager={new MyTokenManager()}
/>

// After
<QuickplayPlatformProvider
  configUrl={configUrl}
  accessTokenProvider={accessTokenProvider}
/>

Handle provider state

Use useQuickplayPlatform to branch UI during startup and failures.

import { useQuickplayPlatform } from '@quickplay/player-react';

function PlatformStatus() {
  const { isLoading, error, reset } = useQuickplayPlatform();

  if (isLoading) return <div>Loading platform services...</div>;
  if (error)
    return (
      <div>
        <p>{error.message}</p>
        <button onClick={() => reset()}>Retry setup</button>
      </div>
    );

  return null;
}

Use platform services in your app

useQuickplayPlatform also returns platformAuthorizer and platformClient. These are borrowed SDK resources. Wait for successful initialization before you use them, don't dispose the authorizer or change the client, and don't cache them across resets or configuration changes. Both are null until configuration is available, and outside a provider.

reset reinitializes SDK authorization with the current authentication source and waits for registration. It rejects if registration fails. It doesn't clear your tokens, log the user out, or switch to anonymous access.

const { platformAuthorizer, platformClient, isLoading, error } =
  useQuickplayPlatform();

Next steps

After provider setup, continue with playback and UI behavior.

• Build playback screens in Integration guide
• Configure player props in API reference
• Tune controls and theming in Customization