@glomex/integration-web-component/README.md

Web component and types to integrate the glomex player

# @glomex/integration-web-component

## Introduction

`@glomex/integration-web-component` exposes a Web Component and types to easily integrate the glomex player. In order to use this component, you need to have a glomex account. You can get one by following the instructions in the [Getting Started](https://docs.glomex.com/publisher/getting-started) section.

If you use React, you can install the [@glomex/integration-react](https://www.npmjs.com/package/@glomex/integration-react) package instead.

## About glomex

[glomex](https://glomex.com) operates Germany’s largest marketplace for premium video content. Our platform connects publishers, content creators, and advertisers, enabling the seamless distribution of high-quality video content across the web.

Our ecosystem is designed to create value for all participants:

- **Publishers** gain access to premium video content and monetization opportunities
- **Content Owners** receive wide distribution and revenue for their video assets
- **Advertisers** reach targeted audiences across a network of quality websites

## Usage

### Loading & integrating the player (TypeScript)

For plain JavaScript projects, you can follow [this guide](https://docs.glomex.com/publisher/player/embed-code/advanced/javascript).
You though can use the `@glomex/integration-web-component` helper to load the integration component and styles also in JavaScript projects.

```ts
import {
  IntegrationEvent,
  ComponentName,
  loadIntegrationComponent,
  loadIntegrationStyles
} from '@glomex/integration-web-component';

// Get the container element where the player will be placed
const container = document.getElementById('player-container-on-site');
const integrationId = 'FILL_IN_INTEGRATION_ID';
const playlistId = 'FILL_IN_PLAYLIST_ID';
// It makes sense to load integration css
// as early as possible to reduce layout shifts.
// You also can get the CSS URL with this helper:
// `import { getIntegrationCssUrl } from '@glomex/integration/load';`
loadIntegrationStyles(integrationId);
// load the integration web component
loadIntegrationComponent();
// create the fully typed integration element
const integration = document.createElement(ComponentName.INTEGRATION);
integration.setAttribute('integration-id', integrationId);
integration.setAttribute('playlist-id', playlistId);
integration.addEventListener(IntegrationEvent.CONTENT_START, () => {
  console.log('content start', integration.content);
});
// attach the integration element
container.appendChild(integration);
// wait until the integration was upgraded to access web component methods
await window.customElements.whenDefined(ComponentName.INTEGRATION);
integration.play();
```

### Implementing a public API script (TypeScript)

```ts
import {
  IntegrationEvent,
  type ConnectIntegration
} from '@glomex/integration-web-component';

// with this you get a fully typed integration
export const connectIntegration: ConnectIntegration = (integration) => {
  integration.addEventListener(IntegrationEvent.CONTENT_PLAY, () => {
    console.log('play', integration.content);
  });
};
```

### Shared Context

Use `getSharedContext()` to provide global application context and provider-specific user tokens to all `<glomex-integration>` instances on the page.

`getSharedContext()` waits for the integration component to be loaded and returns the same singleton instance that the running player uses.

```ts
import { getSharedContext } from '@glomex/integration-web-component';

const sharedContext = await getSharedContext();

sharedContext.set({
  // Plain values — used as-is
  appVersion: '2.3.0',
  appName: 'my-app',
  deviceId: { id: '...', name: 'idfa' },

  // Resolver functions — called each time the player needs the value,
  // so they can return fresh data (e.g. after consent changes)
  userIds: async () => await cmp.getConsentedUserIds(),

  // Provider-specific context (tokens, subscription state, ...)
  providers: {
    'my-provider': async () => ({
      token: await myAuth.getToken(),
      subscriptionState: userState
    })
  }
});
```

Calling `set()` multiple times merges incrementally — previously set values are preserved unless overwritten:

```ts
// Initial setup
sharedContext.set({ appVersion: '2.3.0', appName: 'my-app' });

// Later — adds providers without removing appVersion/appName
sharedContext.set({
  providers: {
    'my-provider': async () => ({ token: await myAuth.getToken() })
  }
});
```