Adaptateurs

Un adaptateur, tel que décrit précédemment, est défini grâce à la classe Adapter exposée par le fichier JavaScript présent à l'adresse suivante :

https://obs.multistream.tools/v1/adapters.js

astuce

Ce fichier/module exporte également un certain nombre de constantes et utilitaires pratiques pour la modélisation d'adaptateurs pour les plateformes de votre choix.

L'API décrite ci-dessous vous permet de développer vos propres adaptateurs pour ajouter le support de n'importe quelle plateforme à notre système générique. Libre à vous d'implémenter par exemple ceux-ci en vous basant directement l'API Twitch ou toute autre disponible en ligne. Vos adaptateurs devront simplement être exécutés dans des pages HTML servies en HTTPS et respecter au minimum les types de données attendus.

API

La signature TypeScript de la classe Adapter est la suivante :

type Id = string;

type Event = string;

type Alerts = Event[];

type Filters = {
  alerts?: false;
  chat?: false;
  session?: true;
  other?: true;
  [key: Event]: false;
};

declare class Platform {
  constructor(filters?: Filters, extraAlerts?: Alerts);
  get id(): Id;
  has(event: Event): boolean;
}

type AlertData = {
  name: string;
  sender?: string;
  message?: string;
  tier?: string;
  amount?: number;
};

type SessionData = {
  [key: string]: object | object[];
};

type LoadData = {
  session: SessionData;
};

type ChatData = object;

type MessageData = {
  renderedText: string;
  data: {
    userId: Id;
    msgId: Id;
    nick: string;
    displayName: string;
  };
};

type DeleteMessageData = {
  msgId: Id;
};

type DeleteMessagesData = {
  userId: Id;
};

type OtherData = object;

declare class Adapter {
  constructor(PlatformClass: typeof Platform, filters?: Filters, extraAlerts?: Alerts);
  has(event: Event): boolean;
  load(data: LoadData): void;
  session(data: SessionData): void;
  alerts(event: Event, data: AlertData, group?: Id, root?: true): void;
  chat(event: Event, data: ChatData): void;
  message(data: MessageData): void;
  'delete-message'(data: DeleteMessageData): void;
  'delete-messages'(data: DeleteMessagesData): void;
  other(event: Event, data: OtherData): void;
  $load?(data: LoadData): void | LoadData;
  $session?(data: SessionData): void | SessionData;
  $alerts?(data: AlertData, event: Event, group?: Id, root?: true): void | AlertData;
  $chat?(data: ChatData, event: Event): void | ChatData;
  $other?(data: OtherData, event: Event): void | OtherData;
}

astuce

Les structures de données (type) listées ci-dessus décrivent l'ensemble des propriétés obligatoires ou optionnelles devant être présentes, vous pouvez évidemment en ajouter de nouvelles !

Paramètres

attention

Chaque paramètre listé ci-dessous n'est plus modifiable une fois l'adaptateur instancié (lecture seule).

Un adaptateur a besoin d'être lié à une plateforme afin que le système puisse identifier la source des événements émis ; c'est le rôle du premier paramètre nommé PlatformClass faisant référence à un constructeur de plateforme que l'adaptateur se chargera d'instancier.

import {
  Platform,
  Adapter
} from 'https://obs.multistream.tools/v1/adapters.js';

class CustomPlatform extends Platform {
  constructor(...args) {
    super('custom', ['alert'], ...args);
  }
}

class CustomPlatformAdapter extends Adapter {
  constructor(...args) {
    super(CustomPlatform, ...args);

    // Implement custom integration logic here.
  }
}

Les paramètres optionnels filters et extraAlerts seront quant à eux directement passés au constructeur PlatformClass à qui ils sont destinés.

import {
  Platform,
  Adapter
} from 'https://obs.multistream.tools/v1/adapters.js';

const customAlert = 'alert';

class CustomPlatform extends Platform {
  constructor(...args) {
    super('custom', [customAlert], ...args);
  }
}

class CustomAdapter extends Adapter {
  constructor(PlatformClass, filters) {
    super(PlatformClass, filters, ['commonAlert']);

    // Implement custom integration logic here.
  }
}

const customPlatformAdapter = new CustomAdapter(CustomPlatform, {
  [customAlert]: false
});

Méthodes

La méthode nommée has est un simple proxy vers celle de l'instance de la classe Platform associée à l'adaptateur.

Les événements émis par une plateforme doivent être triés selon des catégories afin d'être traités correctement par notre système. Ce tri s'effecture au niveau de l'adaptateur dans sa logique d'intégration personnalisée. Les catégories système sont les suivantes :

'load' ; l'événement load doit être émis une seule fois pour indiquer que la plateforme a été chargée correctement
'session' ; l'événement session doit être émis à chaque fois que les données de session liées à la plateforme ont été modifiées, généralement après chaque alerte
'alerts' ; l'événement alerts doit être émis pour chaque alerte déclenchée sur la plateforme par l'action d'un spectateur
'chat' ; l'événement chat doit être émis pour chaque message posté ou supprimé dans le chat de la plateforme
'other' ; l'événement other peut être émis pour couvrir d'éventuels autres cas

Les méthodes présentes sur une instance de la classe Adapter correspondent aux catégories listées ci-dessus et sont donc destinées à être appelées au bon moment et avec les bonnes données pour que les événements associés puissent transiter correctement dans le système Multistream Tools.

import {
  subscriber,
  message,
  botCounter,
  Twitch,
  Adapter
} from 'https://obs.multistream.tools/v1/adapters.js';

class CustomAdapter extends Adapter {
  constructor(PlatformClass, ...args) {
    super(PlatformClass, ...args);

    // Implement custom integration logic here.
    this.load({ session: { /* ... */ } });
  }
}

const customTwitchAdapter = new CustomAdapter(Twitch);

const name = 'TheFrenchBiff';

const subscriberData = { name };

customTwitchAdapter.alerts(subscriber, subscriberData);

customTwitchAdapter.session({ [`${subscriber}-latest`]: subscriberData });

customTwitchAdapter.chat(botCounter, { counter: 'power', value: 9001 });

const userId = crypto.randomUUID();
const msgId = crypto.randomUUID();

customTwitchAdapter.message({
  renderedText: `test ${message}`,
  data: {
    userId,
    msgId,
    nick: name.toLowerCase(),
    displayName: name
  }
});

customTwitchAdapter['delete-message']({ msgId });

customTwitchAdapter['delete-messages']({ userId });

customTwitchAdapter.other('notCategorized', { /* ... */ });

Les paramètres optionnels, nommés group et root, de la méthode alerts permettent de lier pusieurs événements entre eux, notamment pour l'affichage dans notre dock. Un événement racine - indiqué par le paramètre root - doit toujours être émis en premier lieu, suivi de tous ceux à regrouper ; la valeur du paramètre group devra donc être un identiant unique partagé par tous ces événements. Ceci peut être utilisé par exemple dans le cas d'abonnements offerts :

const group = crypto.randomUUID();

customTwitchAdapter.alerts(subscriber, { name, amount: 2 }, group, true);
customTwitchAdapter.alerts(subscriber, { name: 'userA', sender: name }, group);
customTwitchAdapter.alerts(subscriber, { name: 'userB', sender: name }, group);

Les méthodes message, delete-message et delete-messages appellent en interne la méthode chat en passant respectivement à celle-ci 'message', 'delete-message' et 'delete-messages' comme premier paramètre pour plus de praticité. Il s'agit donc de raccourcis à privilégier.

Les méthodes optionnelles $load, $session, $alerts, $chat et $other permettent de transformer les données recues avant que celles-ci soient envoyées vers notre système. Ceci peut être utile pour corriger d'éventuels problèmes de cohérence, soit en mutant directement l'objet data passé en premier paramètre, soit en retournant un nouvel objet. Ces méthodes ne sont jamais appelées pour les alertes/catégories désactivées par le biais de filters.

Pour un exemple pratique, rendez-vous sur notre page dédiée au développement d'adaptateurs.

Adaptateurs pré-configurés

Nous fournissons les adaptateurs suivants exposés par le même fichier JavaScript cité tout au long de cette page. Pour consulter leurs instructions d'installation respectives, rendez-vous sur la page dédiée.

classe	plateforme	intégration
`FacebookStreamElementsAdapter`	`Facebook`	StreamElements
`TrovoStreamElementsAdapter`	`Trovo`	StreamElements
`TwitchStreamElementsAdapter`	`Twitch`	StreamElements
`YouTubeStreamElementsAdapter`	`YouTube`	StreamElements

Leurs signatures TypeScript sont les suivantes :

type WidgetLoadData = {
  session: {
    data: SessionData;
  };
};

type SessionUpdateData = {
  session: SessionData;
};

type EventReceivedData = {
  listener: Event;
  event: AlertsData | ChatData | OtherData;
};

declare class StreamElementsAdapter extends Adapter {
  constructor(PlatformClass: typeof Platform, filters?: Filters);
  $load(data: LoadData): void | LoadData;
  $alerts(data: AlertData, event: Event, group?: Id, root?: true): void | AlertData;
  onWidgetLoad(data: WidgetLoadData): void;
  onEventReceived(data: EventReceivedData): void;
  onSessionUpdate(data: SessionUpdateData): void;
}

declare class FacebookStreamElementsAdapter extends StreamElementsAdapter {
  constructor(filters?: Filters);
}

declare class TrovoStreamElementsAdapter extends StreamElementsAdapter {
  constructor(filters?: Filters);
}

declare class TwitchStreamElementsAdapter extends StreamElementsAdapter {
  constructor(filters?: Filters);
}

declare class YouTubeStreamElementsAdapter extends StreamElementsAdapter {
  constructor(filters?: Filters);
}

info

Les méthodes onWidgetLoad, onEventReceived et onSessionUpdate de la classe StreamElementsAdapter correspondent aux événements des widgets personnalisés, fonctionnalité proposée par le service tiers StreamElements.

Adaptateurs

API​

Paramètres​

Méthodes​

Adaptateurs pré-configurés​

API

Paramètres

Méthodes

Adaptateurs pré-configurés