# host events, fullscreen and device

sdk.on() delivers pause, resume, consent and locale from the host; sdk.fullscreen() asks for fullscreen; sdk.device() says phone, tablet or desktop.

## `on(type, listener): Off`

Four host events. `on()` works at any time, before `init()` included, and returns a function that removes
the listener.

| Event     | Value                                  | When                                                                                                                          |
| --------- | -------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `pause`   | none                                   | The host hid or covered the game: the hub's `filudi:pause`, a Playgama visibility change, the page going hidden on every host |
| `resume`  | none                                   | The game is visible again. `pause` fires once when the first source pauses, `resume` once when the last one resumes           |
| `consent` | `{ ads: boolean, analytics: boolean }` | The player changed consent on filudi.com                                                                                      |
| `locale`  | the new tag                            | Same as `sdk.i18n.on('change')`                                                                                               |

<CodePanel title="Pause and resume">
  <Fragment slot="javascript">
    ```js
    sdk.on('pause', () => game.pause());
    sdk.on('resume', () => game.resume());
    sdk.on('consent', (consent) => analyticsAllowed = consent.analytics);
    ```

  </Fragment>
  <Fragment slot="typescript">
    ```ts
    import type { Consent } from '@filudi/game-sdk';

    sdk.on('pause', () => game.pause());
    sdk.on('resume', () => game.resume());
    sdk.on('consent', (consent: Consent) => { analyticsAllowed = consent.analytics; });
    ```

  </Fragment>
</CodePanel>

A paused game stops its clock and its audio. It does not call `gameplay.stop()` for the pause the host
caused: the SDK does not either, and a session that spans a hidden tab is still one session.

## `fullscreen(): Promise<boolean>`

Resolves `true` when the frame is now fullscreen. On filudi.com the SDK asks the hub, which applies the
Fullscreen API to the frame and answers; the SDK resolves with that answer, or `false` after 2 s. Elsewhere
the SDK calls `document.documentElement.requestFullscreen()` itself. Call it from a click: browsers refuse
fullscreen without a gesture, and the hub answers `false` unless the player just clicked inside the game.

<CodePanel title="A fullscreen button">
  <Fragment slot="javascript">
    ```js
    fullscreenButton.hidden = result.host === 'crazygames';   // the portal draws its own
    fullscreenButton.addEventListener('click', async () => {
      const ok = await sdk.fullscreen();
      if (!ok) fullscreenButton.hidden = true;
    });
    ```

  </Fragment>
  <Fragment slot="typescript">
    ```ts
    fullscreenButton.hidden = result.host === 'crazygames';   // the portal draws its own
    fullscreenButton.addEventListener('click', async () => {
      const ok: boolean = await sdk.fullscreen();
      if (!ok) fullscreenButton.hidden = true;
    });
    ```

  </Fragment>
</CodePanel>

## `device(): Device`

`'desktop' | 'tablet' | 'mobile'`. From the host when it knows (CrazyGames `systemInfo.device.type`,
Playgama `bridge.device.type`), else from `navigator.userAgentData` or a pointer and width heuristic. Read
it after `init()`; it throws before. Use it for a default layout, not for input: a desktop can have a touch
screen.

<CodePanel title="Default layout">
  <Fragment slot="javascript">
    ```js
    const touchFirst = sdk.device() !== 'desktop';
    showOnScreenButtons(touchFirst);
    ```

  </Fragment>
  <Fragment slot="typescript">
    ```ts
    import type { Device } from '@filudi/game-sdk';

    const device: Device = sdk.device();
    showOnScreenButtons(device !== 'desktop');
    ```

  </Fragment>
</CodePanel>

## Unavailable cases

`fullscreen()` resolves `false` when the host or the browser refuses. The events fire on every host or not
at all: a host without consent or locale changes never emits them.