Mit OpenReplay Assist unterstützen Sie Ihre Benutzer, indem Sie deren Live-Bildschirm sehen und sofort einen Anruf (WebRTC) mit ihnen starten – ganz ohne Screen-Sharing-Software von Drittanbietern.

npm i @openreplay/tracker-assist

Wenn Ihr OpenReplay-Tracker über das JS-Snippet eingerichtet ist, ersetzen Sie einfach das Vorkommen von .../openreplay.js durch .../openreplay-assist.js. Das folgende Beispiel zeigt, wie das Skript nach der Änderung aussehen sollte:

<!-- OpenReplay Tracking Code -->
<script>
var initOpts = { projectKey: "GxPpaDARdn2345fgt321" };
var startOpts = { userID: "" };
(function(A,s,a,y,e,r){
  r=window.OpenReplay=[e,r,y,[s-1, e]];
  s=document.createElement('script');s.src=A;s.async=!a;
  ...
})("//static.openreplay.com/latest/openreplay-assist.js", 1, 0, initOpts, startOpts);
</script>

Initialisieren Sie den Tracker und laden Sie anschließend das Plugin @openreplay/tracker-assist.

import trackerAssist from '@openreplay/tracker-assist';
import { tracker } from '@openreplay/tracker';

tracker.configure({
  projectKey: 'YOUR_PROJECT_KEY',
  ingestPoint: "https://openreplay.mydomain.com/ingest", // when dealing with the self-hosted version of OpenReplay
});
tracker.use(trackerAssist(options)); // check the list of available options below

tracker.start();

Orientieren Sie sich am folgenden Beispiel, wenn Ihre App SSR verwendet. Stellen Sie sicher, dass tracker.start() aufgerufen wird, sobald sich die App in der Browserumgebung befindet (z. B. über useEffect oder componentDidMount).

import trackerAssist from '@openreplay/tracker-assist';
import { tracker } from '@openreplay/tracker';

tracker.configure({
  projectKey: 'YOUR_PROJECT_KEY',
  ingestPoint: "https://openreplay.mydomain.com/ingest", // when dealing with the self-hosted version of OpenReplay
});
tracker.use(trackerAssist(options)); // check the list of available options below

//...
function MyApp() {
  useEffect(() => { // use componentDidMount in case of React Class Component
    tracker.start();
  }, [])
//...
}

Das Assist-Plugin unterstützt die folgenden Optionen:

trackerAssist({
  callConfirm?: string|ConfirmOptions;
  controlConfirm?: string|ConfirmOptions;
  config?: object;
  onAgentConnect?: () => (()=>void | void);
  onCallStart?: () => (()=>void | void);
  onRemoteControlStart?: () => (()=>void | void);
  onCallDeny?: () => any;
  onRemoteControlDeny?: (agentInfo: Record<string, any>) => any;
  onRecordingDeny?: (agentInfo: Record<string, any>) => any;
  onDragCamera?: (dx: number, dy: number) => any;
  callUITemplate?: string
  /** 
   * enables gzip compression for big batches on client side
   * */
  compressionEnabled: boolean;
  /**
   * Minimum amount of MESSAGES in a batch to trigger compression run
   * @default 5000
   * */
  compressionMinBatchSize: number;
  /**
   * Show only the first part of an agent's name in the call popup
   * (e.g. "One Two" -> "One").
   * @default false
   */
  agentShortNames: boolean;
  /**
   * Postpone assist start until a userID is set on the session.
   * @default false
   */
  ignoreAnonymous: boolean;
  /**
   * When assist connects to the server:
   * - Autostart.Auto (default): always on tracker start.
   * - Autostart.Disabled: only via an explicit start() call.
   * - Autostart.Continuation: only via assist.start(), but the choice is remembered
   *   in sessionStorage so it auto-continues across page reloads until assist.stop().
   * @default Autostart.Auto
   */
  autostart: Autostart;
  /**
   * Require explicit user confirmation before anything is shared with an
   * agent: assist starts and opens the socket as usual, but no messages are
   * sent through it until the user approves the confirmation popup, which is
   * shown as soon as the first agent connects to the session. The approval
   * is remembered per-tab (sessionStorage) until stop() is called.
   * @default false
   */
  requestConfirm: boolean;
  /** Text/style customization for the session view confirmation popup. */
  sessionConfirm?: ConfirmOptions;
  /** Called when the user approves session viewing (requestConfirm mode). */
  onSessionConfirmApprove?: (agentInfo: Record<string, any>) => any;
  /** Called when the user denies session viewing (requestConfirm mode). */
  onSessionConfirmDeny?: (agentInfo: Record<string, any>) => any;
})

Die Widgets für die Live-Ansicht, die Fernsteuerung und den Anruf, die der Endbenutzer sieht, lassen sich vollständig anpassen.

Setzen Sie requestConfirm: true, um die Erlaubnis des Benutzers einzuholen, bevor ein Agent dessen Sitzung live ansehen kann. Assist startet und verbindet sich wie gewohnt, aber die Sitzung bleibt für den Agent unsichtbar, bis der Benutzer das Bestätigungs-Popup genehmigt, das angezeigt wird, sobald sich der erste Agent verbindet. Nach der Zustimmung wird das Tracking neu gestartet, und der Agent kann die Sitzung des Benutzers live sehen. Die Zustimmung wird gespeichert, bis stop() aufgerufen wird und sie widerruft, sodass beim nächsten start() erneut gefragt wird.

tracker.use(trackerAssist({
  requestConfirm: true,
  sessionConfirm: { text: 'A support agent would like to view your screen. Allow?' },
  onSessionConfirmApprove: ({ email, name, query }) => console.log("Session viewing approved"),
  onSessionConfirmDeny: ({ email, name, query }) => console.log("Session viewing denied"),
}));

Text und Stil des Popups lassen sich über die Option sessionConfirm anpassen, die das folgende ConfirmOptions-Objekt entgegennimmt:

type ConfirmOptions = {
  text?:string,
  style?: StyleObject, // style object (i.e {color: 'red', borderRadius: '10px'})
  confirmBtn?: ButtonOptions, 
  declineBtn?: ButtonOptions
}

type ButtonOptions = HTMLButtonElement | string | {
  innerHTML?: string, // to pass an svg string or text
  style?: StyleObject, // style object (i.e {color: 'red', borderRadius: '10px'})
}

Text und Stil des Popups lassen sich über die Option controlConfirm anpassen, die das folgende ConfirmOptions-Objekt entgegennimmt:

type ConfirmOptions = {
  text?:string,
  style?: StyleObject, // style object (i.e {color: 'red', borderRadius: '10px'})
  confirmBtn?: ButtonOptions, 
  declineBtn?: ButtonOptions
}

type ButtonOptions = HTMLButtonElement | string | {
  innerHTML?: string, // to pass an svg string or text
  style?: StyleObject, // style object (i.e {color: 'red', borderRadius: '10px'})
}

Text und Stil des Popups lassen sich über die Option callConfirm anpassen, die das folgende ConfirmOptions-Objekt entgegennimmt:

type ConfirmOptions = {
  text?:string,
  style?: StyleObject, // style object (i.e {color: 'red', borderRadius: '10px'})
  confirmBtn?: ButtonOptions, 
  declineBtn?: ButtonOptions
}

type ButtonOptions = HTMLButtonElement | string | {
  innerHTML?: string, // to pass an svg string or text
  style?: StyleObject, // style object (i.e {color: 'red', borderRadius: '10px'})
}

Sie können außerdem jeden Aspekt dieses Widgets über die folgenden ids und classes anpassen. Ids dienen als Anker für einzelne Schaltflächen/Elemente, während classes für Gruppen-Container verwendet werden können.

Hier ist die Liste aller Callbacks:

• callConfirm: Passt Text und/oder Layout des Popups für Anrufanfragen an.
• controlConfirm: Passt Text und/oder Layout des Popups für Fernsteuerungsanfragen an.
• config: Enthält eine benutzerdefinierte ICE/TURN-Serverkonfiguration. Standardwert: { 'iceServers': [{ 'urls': 'stun:stun.l.google.com:19302' }], 'sdpSemantics': 'unified-plan' }.
• onAgentConnect: () => (()=>void | void): Diese Callback-Funktion wird ausgelöst, sobald eine Live-Sitzung beginnt, und liefert die Details des Agents zurück (email, name und query). Sie kann außerdem onAgentDisconnect zurückgeben, das aufgerufen wird, wenn die Sitzung getrennt wird. Bei einer instabilen Verbindung kann sie mehrfach aufgerufen werden. Nachfolgend ein Beispiel:

onAgentConnect = ({ email, name, query }) => {
  console.log("Live session started")
  const onAgentDisconnect =  () => console.log("Live session stopped")
  return onAgentDisconnect
}

• onCallStart: ({ email, name, query }) => (()=>void | void): Diese Callback-Funktion wird ausgelöst, sobald ein Anruf (WebRTC) beginnt, und liefert die Details des Agents zurück (email, name und query). Sie kann außerdem onCallEnd zurückgeben, das aufgerufen wird, wenn der Anruf endet. Bei einer instabilen Verbindung kann sie mehrfach aufgerufen werden. Nachfolgend ein Beispiel:

onCallStart: () => {
  console.log("Call started")
  const onCallEnd = () => console.log("Call ended")
  return onCallEnd
}

• onRemoteControlStart: ({ email, name, query }) => (()=>void | void): Diese Callback-Funktion wird ausgelöst, sobald eine Fernsteuerungssitzung beginnt, und liefert die Details des Agents zurück (email, name und query). Sie kann außerdem onRemoteControlEnd zurückgeben, das aufgerufen wird, wenn die Fernsteuerungsberechtigungen widerrufen werden. Nachfolgend ein Beispiel:

onRemoteControlStart: () => {
  console.log("Remote control started")
  const onControlEnd = () => console.log("Remote control ended")
  return onControlEnd
}

• onCallDeny?: () => any;: Diese Callback-Funktion wird ausgelöst, wenn ein Benutzer den Anruf in der Anfragephase abgelehnt hat.

onCallDeny: () => {
  console.log("Call denied")
}

• onRemoteControlDeny?: (agentInfo: Record<string, any>) => any;: Diese Callback-Funktion wird ausgelöst, wenn ein Benutzer die Fernsteuerungssitzung in der Anfragephase abgelehnt hat, und liefert die Details des Agents zurück (email, name und query).

onRemoteControlDeny: ({ email, name, query }) => {
  console.log("Remote control request denied for", email)
}

• onRecordingDeny?: (agentInfo: Record<string, any>) => any;: Diese Callback-Funktion wird ausgelöst, wenn ein Benutzer die Aufzeichnung der Sitzung in der Anfragephase abgelehnt hat, und liefert die Details des Agents zurück (email, name und query).

onRecordingDeny: ({ email, name, query }) => {
  console.log("Recording session denied")
 
}

• onSessionConfirmApprove?: (agentInfo: Record<string, any>) => any;: Diese Callback-Funktion wird ausgelöst, wenn der Benutzer die Sitzungsansicht genehmigt (im Modus requestConfirm), und liefert die Details des Agents zurück (email, name und query).

onSessionConfirmApprove: ({ email, name, query }) => {
  console.log("Session viewing approved for", email)
}

• onSessionConfirmDeny?: (agentInfo: Record<string, any>) => any;: Diese Callback-Funktion wird ausgelöst, wenn der Benutzer die Sitzungsansicht ablehnt (im Modus requestConfirm), und liefert die Details des Agents zurück (email, name und query).

onSessionConfirmDeny: ({ email, name, query }) => {
  console.log("Session viewing denied")
}

• onDragCamera?: (dx: number, dy: number) => any;: Diese Funktion erwartet einen Handler, der das Verhalten einer gedrückt gehaltenen Maustaste innerhalb eines Three.js-Canvas für die Fernsteuerung festlegt. Der Handler erhält dx und dy, die die Mausbewegungs-Deltas angeben.

onDragCamera: (dx, dy) => {
  moveCamera(dx, dy)
}

tracker.use() gibt die Assist-Instanz zurück, die Methoden zur Steuerung von Assist zur Laufzeit bereitstellt:

const assist = tracker.use(trackerAssist(options));

assist.stop();
assist.start();

• start(): Startet Assist (neu). Der Aufruf bleibt wirkungslos, wenn der Tracker selbst noch nicht aktiv ist (Assist startet dann zusammen mit dem Tracker). Im Modus Autostart.Continuation wird ein Flag in sessionStorage gespeichert, damit Assist über Seiten-Neuladungen hinweg automatisch fortgesetzt wird. Ein expliziter start()-Aufruf hebt außerdem jede Verzögerung durch ignoreAnonymous auf.
• stop(): Stoppt Assist, indem die Socket-Verbindung getrennt und alle Verbindungen bereinigt werden. Assist startet erst wieder automatisch, wenn start() aufgerufen wird. Im Modus Autostart.Continuation wird dabei auch das gespeicherte Flag gelöscht, sodass ein Neuladen nicht automatisch fortgesetzt wird. Im Modus requestConfirm wird außerdem die Zustimmung des Benutzers widerrufen, sodass beim nächsten start() erneut gefragt wird.

Haben Sie Probleme bei der Einrichtung dieses Plugins? Verbinden Sie sich mit unserem Slack und holen Sie sich Hilfe von unserer Community.