Konfigurierbare TURN-Server

Übersicht

  • Client SDK: Bitte beachten Sie, dass Ihr App-ID ist Ihr API-Schlüssel.

Sie können die TURN-Server-Nutzung für jeden Client in der Sitzung auf folgende Weise anpassen:

  • Sie können eine Liste mit Ihren eigenen TURN-Servern hinzufügen, die der Client verwenden soll.

  • Sie können entscheiden, ob der Client ausschließlich Ihre TURN-Server oder zusätzlich zu den Vonage TURN-Servern verwenden soll. zusätzlich zu den Vonage TURN-Servern

Das Hinzufügen eigener TURN-Server kann Benutzern helfen, sich in restriktiven Netzwerkumgebungen zu verbinden, in denen Vonage TURN-Server möglicherweise blockiert werden.

Wenn Sie sich dafür entscheiden, die Vonage TURN-Server außer Kraft zu setzen und nur Ihre eigenen TURN-Server zu verwenden, können Sie können Sie sicherstellen, dass Medienströme niemals Ihr Netzwerk verlassen.

Du kannst deine eigenen TURN-Server für jeden Client hinzufügen, der sich mit der Sitzung verbindet, indem du OpenTok.js (für Web-Clients), dem iOS SDK oder dem Android SDK. Die eigene TURN-Server-API wurde in Version 2.13.0 dieser Client-SDKs hinzugefügt.

Außerdem gibt es eine IP-Proxy Add-on-Funktion, mit der Sie Sie Ihren eigenen Proxyserver verwenden können, um die Nicht-Medien Datenverkehr, z. B. Video API-Aufrufe, WebSocket-Verbindungen und Protokolldatenverkehr.

OpenTok.js (ab Version 2.13.0)

Die options Parameter des OT.initSession() Methode enthält eine undokumentierte iceConfig Eigenschaft. Diese Eigenschaft umfasst die folgenden Eigenschaften:

  • includeServers (String) - Setzen Sie dies auf 'custom' und der Client verwendet nur die benutzerdefinierten TURN-Server, die Sie in der customServers Array. Setzen Sie dies auf 'all' (die Standardeinstellung) und der Client verwendet sowohl die von Ihnen bereitgestellten benutzerdefinierten TURN-Server als auch die TURN-Server von Vonage.

  • transportPolicy (String) - Setzen Sie dies auf 'all' (die Standardeinstellung) und der Client verwendet alle ICE-Transporttypen (z. B. Host, srflx und TURN), um die Medienkonnektivität herzustellen. Setzen Sie dies auf 'relay' die Konnektivität immer über TURN zu erzwingen und alle anderen ICE-Kandidaten zu ignorieren Kandidaten.

  • customServers (Array) - Setzen Sie dies auf ein Array von Objekten, die Ihre benutzerdefinierten TURN-Server definieren. Jedes Objekt entspricht einem benutzerdefinierten TURN-Server, und es enthält die folgenden Eigenschaften:

    • urls (String oder Array von Strings) - Ein String oder ein Array von Strings, wobei jeder String eine vom TURN-Server unterstützte URL ist (und dies darf nur eine URL sein).

    • username (String) - Der Benutzername für den in diesem Objekt definierten TURN-Server.

    • credential (String) - Der Credential-String für den in diesem Objekt definierten TURN-Server Objekt definiert ist.

Anmerkung: Damit der Client nur die von Ihnen angegebenen TURN-Server verwendet (und nicht die die Vonage TURN-Server): Setzen Sie die includeServers Eigenschaft zu 'custom'setzen Sie die transportPolicy Eigenschaft zu 'relay'und setzen die customServers Eigenschaft, um Ihre TURN-Server.

Um benutzerdefinierte TURN-Anmeldeinformationen dynamisch zu aktualisieren, verwenden Sie die Session.setIceConfig() Methode.

Das folgende Beispiel zeigt, wie man TURN-Server für den Client konfiguriert:

const session = OT.initSession(projectId, sessionId, {
  iceConfig: {
    includeServers: 'custom',
    transportPolicy: 'relay',
    customServers: [
      {
        urls: [
          'turn:123.124.125.126:3478?transport=udp',
          'turn:123.124.125.126:3478?transport=tcp'
        ],
        username: 'webrtc',
        credential: 'foO0Bar1'
      },
      {
          urls: [
            'turns:turntls.example.com:3478?transport=tcp'
          ],
          username: 'webrtc',
          credential: 'foO0Bar2',
      },
    ],
  },
});

Android-SDK

Die Session.Builder Klasse enthält zwei Methoden zur Konfiguration der TURN-Server-Nutzung für den Client:

  • Session.Builder.setCustomIceServers() - Rufen Sie diese Methode auf, um eine Liste von benutzerdefinierten TURN Servern für den Client hinzuzufügen.

  • Session.Builder.setIceRouting() - Rufen Sie diese Methode auf, um die Begrenzung der ICE Optionen für den Client hinzuzufügen.

Zusätzlich zu den beiden neuen Methoden definieren zwei neue Enums die Optionen des TURN-Servers:

  • IncludeServers - Enthält Optionen für die Verwendung nur der benutzerdefinierten Server oder sowohl der Vonage-Servern und den benutzerdefinierten Servern.

  • TransportPolicy - Beschreibt die zu verwendende Routing-Methode.

Anmerkung: Damit der Client nur die von Ihnen angegebenen TURN-Server verwendet (und nicht die die Vonage TURN-Server), rufen Sie die folgenden Methoden des Session.Builder Objekts auf, das Sie zum Erstellen des Session-Objekts verwenden:

  • setCustomIceServers() - Übergeben Sie eine Liste von IceServer-Objekten (die Ihren benutzerdefinierten TURN-Servern entsprechen) als serverList Parameter, und einreichen IncludeServers.TURN als die config Parameter.

  • setIceRouting() - Einreichen TransportPolicy.Relay.

Das folgende Beispiel zeigt, wie man TURN-Server für den Client konfiguriert:

List<IceServer> serverList = new IceServer(
  'turn:123.124.125.126:3478?transport=udp', // TURN server URL
  'webrtc', // Username
  'foO0Bar1' // Credential
);
mSession = new Session.Builder(this, apiKey, sessionId)
  .setCustomIceServers(serverList, IncludeServers.Custom)
  .setIceRouting(TransportPolicy.TURN)
  .build();
mSession.setSessionListener(this);
mSession.connect(token);

iOS-SDK

Wenn Sie ein OTSession-Objekt initialisieren, setzen Sie die OTSessionSettings.iceConfig Eigenschaft, um eine benutzerdefinierte TURN-Server-Konfiguration für den Client zu definieren. Die Klasse OTSessionICEConfig definiert die OTSessionSettings.iceConfig Eigentum.

Anmerkung: Damit der Client nur die von Ihnen angegebenen TURN-Server verwendet (und nicht die die Vonage TURN-Server), rufen Sie die Funktion [OTSessionSettings addICEServerWithURL:] Methode des des OTSessionSettings-Objekts, das Sie zur Erstellung des OTSession-Objekts verwenden. Setzen Sie dann die die folgenden Eigenschaften des OTSessionSettings-Objekts:

  • includeServers - Setzen Sie dies auf OTSessionICEIncludeServersCustom.

  • transportPolicy - Setzen Sie dies auf OTSessionICETransportRelay.

Sie können die OTSessionICEConfig.filterOutLanCandidates Eigenschaft, um zu verhindern, dass Clients im selben lokalen Netzwerk in weitergeleiteten Sitzungen abonniert werden, was dazu führt, dass die App den Benutzer unter iOS 14+ um Erlaubnis bittet. Beachten Sie, dass diese Funktion nicht benötigen das konfigurierbare TURN-Zusatzmodul. Für mehr Informationen, siehe dieses Thema.

Das folgende Beispiel zeigt, wie man TURN-Server für den Client konfiguriert:

OTSessionICEConfig *myICEServerConfiguration = [[OTSessionICEConfig alloc] init];
myICEServerConfiguration.includeServers = OTSessionICEIncludeServersCustom;
myICEServerConfiguration.transportPolicy = OTSessionICETransportForceTurn

NSError *error = nil;
[myICEServerConfiguration addICEServerWithURL:@"turn:123.124.125.126:3478?transport=udp"
                                     userName:@"webrtc"
                                   credential:@"foO0Bar1"
                                        error:&error];

OTSessionSettings *settings = [[OTSessionSettings alloc] init];
settings.iceConfig = myICEServerConfiguration;

_session = [[OTSession alloc] initWithApiKey:kApiKey
                                   sessionId:kSessionId
                                    delegate:self
                                    settings:settings];

Windows-SDK

Verwenden Sie die IceConfig-Klasse, um die benutzerdefinierte ICE-Konfiguration die vom Client verwendet werden soll.

Die IceConfig() Konstruktormethode enthält die folgenden Parameter:

  • customIceServers -- Setzen Sie dies auf Eine Liste von IceServer-Objekten, die benutzerdefinierte TURN-Server, die vom Client verwendet werden sollen. Für jeden IceServer setzen Sie die URL, den Benutzernamen und den Credential-String für den benutzerdefinierten TURN-Server

  • transportPolicy -- Setzen Sie dies auf einen Wert in der ICETransport enum:

    • All -- Der Client verwendet alle ICE-Kandidatentypen (wie Host, srflx und Relay) um die Medienkonnektivität herzustellen.

    • Relayed -- Der Client erzwingt die Konnektivität immer über TURN und ignoriert alle anderen ICE-Kandidaten.

  • includeServers -- Setzen Sie dies auf einen Wert in der IncludeServers enum:

    • All -- Der Kunde verwendet Vonage TURN-Server zusätzlich zu den den von Ihnen bereitgestellten TURN-Servern.

    • Custom -- Der Client wird nur die von Ihnen bereitgestellten TURN-Server verwenden.

Die Klasse Session.Builder enthält eine IceConfig Eigenschaft. Setzen Sie diese bei der Erstellung des Session-Objekts auf ein IceConfig-Objekt. Das folgende Beispiel zeigt, wie man TURN-Server für den Client konfiguriert:

macOS-SDK

Der Typ otc_custom_ice_config definiert eine Struktur, die die folgenden Mitglieder enthält:

  • num_ice_servers -- Die Anzahl der ICE-Server
  • ice_url -- Ein Array von Strings, die Ihre ICE-Server-URLs angeben.
  • ice_user -- Ein Array von Strings, die Benutzernamen für die TURN-Server angeben.
  • ice_credential -- Ein Array von Zeichenketten, die Anmeldeinformationen für die TURN-Server angeben. Rufen Sie die otc_session_settings_set_custom_ice_config() Funktion und geben Sie die otc_custom_ice_config Instanz:
otc_session_settings_set_custom_ice_config(session_settings,
                                           &ice_config);

Das folgende Beispiel zeigt, wie man TURN-Server für den Client konfiguriert:

// Provide the ICE configuration here.
struct otc_custom_ice_config ice_config;
ice_config.num_ice_servers = 1;
ice_config.ice_url = (char **)malloc(sizeof(char *) * ice_config.num_ice_servers);
ice_config.ice_url[0] = strdup("turn:123.124.125.126:3478?transport=udp");
ice_config.ice_user = (char **)malloc(sizeof(char *) * ice_config.num_ice_servers);
ice_config.ice_user[0] = strdup("webrtc");
ice_config.ice_credential = (char **)malloc(sizeof(char *) * ice_config.num_ice_servers);
ice_config.ice_credential[0] = strdup("foO0Bar1");
ice_config.force_turn = OTC_TRUE;
ice_config.use_custom_turn_only = OTC_FALSE;
otc_session_settings *session_settings = otc_session_settings_new();
if (session_settings != NULL) {
  otc_session_settings_set_custom_ice_config(session_settings,
                                             &ice_config);
}
otc_session *session = NULL;
session = otc_session_new_with_settings(API_KEY,
                                        SESSION_ID,
                                        &session_callbacks,
                                        session_settings);
if (session == NULL) {
  printf("Could not create session successfully");
  return EXIT_FAILURE;
}
otc_session_connect(session, TOKEN);

Linux-SDK

Der Typ otc_custom_ice_config definiert eine Struktur, die die folgenden Mitglieder enthält:

  • num_ice_servers -- Die Anzahl der ICE-Server

  • ice_url -- Ein Array von Strings, die Ihre ICE-Server-URLs angeben.

  • ice_user -- Ein Array von Strings, die Benutzernamen für die TURN-Server angeben.

  • ice_credential -- Ein Array von Zeichenketten, die Anmeldeinformationen für die TURN-Server angeben.

Rufen Sie die otc_session_settings_set_custom_ice_config() Funktion und geben Sie die otc_custom_ice_config Instanz:

otc_session_settings_set_custom_ice_config(session_settings,
                                           &ice_config);

Das folgende Beispiel zeigt, wie man TURN-Server für den Client konfiguriert:

// Provide the ICE configuration here.
struct otc_custom_ice_config ice_config;
ice_config.num_ice_servers = 1;
ice_config.ice_url = (char **)malloc(sizeof(char *) * ice_config.num_ice_servers);
ice_config.ice_url[0] = strdup("turn:123.124.125.126:3478?transport=udp");
ice_config.ice_user = (char **)malloc(sizeof(char *) * ice_config.num_ice_servers);
ice_config.ice_user[0] = strdup("webrtc");
ice_config.ice_credential = (char **)malloc(sizeof(char *) * ice_config.num_ice_servers);
ice_config.ice_credential[0] = strdup("foO0Bar1");
ice_config.force_turn = OTC_TRUE;
ice_config.use_custom_turn_only = OTC_FALSE;

otc_session_settings *session_settings = otc_session_settings_new();
if (session_settings != NULL) {
  otc_session_settings_set_custom_ice_config(session_settings,
                                             &ice_config);
}

otc_session *session = NULL;

session = otc_session_new_with_settings(API_KEY,
                                        SESSION_ID,
                                        &session_callbacks,
                                        session_settings);

if (session == NULL) {
  printf("Could not create session successfully");
  return EXIT_FAILURE;
}

otc_session_connect(session, TOKEN);

React Native SDK

Die options Stütze des OTSession Komponente umfasst eine iceConfig Eigenschaft. Dieses Objekt umfasst die folgenden Eigenschaften:

  • includeServers (String) - Setzen Sie dies auf 'custom' und der Client verwendet nur die benutzerdefinierten TURN-Server, die Sie in der customServers Array. Setzen Sie dies auf 'all' (der Standard) und der Client verwendet sowohl die von Ihnen bereitgestellten benutzerdefinierten TURN-Server als auch die OpenTok-TURN-Server.

  • transportPolicy (String) - Setzen Sie dies auf 'all' (die Standardeinstellung) und der Client verwendet alle ICE-Transporttypen (z. B. Host, srflx und TURN), um die Medienkonnektivität herzustellen. Setzen Sie dies auf 'relay' die Konnektivität immer über TURN zu erzwingen und alle anderen ICE-Kandidaten zu ignorieren Kandidaten.

  • customServers (Array) - Setzen Sie dies auf ein Array von Objekten, die Ihre benutzerdefinierten TURN-Server definieren. Jedes Objekt entspricht einem benutzerdefinierten TURN-Server, und es enthält die folgenden Eigenschaften:

    • urls (String oder Array von Strings) - Ein String oder ein Array von Strings, wobei jeder String eine vom TURN-Server unterstützte URL ist (und dies darf nur eine URL sein).

    • username (String) - Der Benutzername für den in diesem Objekt definierten TURN-Server.

    • credential (String) - Der Credential-String für den in diesem Objekt definierten TURN-Server Objekt definiert ist.

Anmerkung: Damit der Client nur die von Ihnen angegebenen TURN-Server verwendet (und nicht die die OpenTok-TURN-Server): Setzen Sie die includeServers Eigenschaft zu 'custom'setzen Sie die transportPolicy Eigenschaft zu 'relay'und setzen die customServers Eigenschaft, um Ihre TURN-Server.

Das folgende Beispiel zeigt, wie man TURN-Server für den Client konfiguriert:

<OTSession
  applicationId="your-application-id"
  sessionId="your-session-id"
  token="your-session-token"
  options={{
    iceConfig:{
      transportPolicy: 'all',
      includeServers: 'all',
      customServers: [
        {
        urls: [
          'turn:123.124.125.126:3478?transport=udp',
          'turn:123.124.125.126:3478?transport=tcp'
        ],
        username: 'webrtc',
        credential: 'foO0Bar1'
        },
      ],
    }
  }}
>
  <OTPublisher style={{ width: 600, height: 400 }}/>
  <OTSubscriber style={{ width: 600, height: 400 }} />
</OTSession>

Bekanntes Problem

Wenn Sie einen Client so einstellen, dass er immer die TURN-Server in einer weitergeleitete Sitzungkann er nicht seine eigenen Streams zu abonnieren (Streams, die er veröffentlicht).

FAQs

Löst die konfigurierbare TURN-API das Problem des HTTP-Verkehrs?

Nein. Konfigurierbares TURN zerstreut die Bedenken der Kunden bezüglich der Verbindung zu vertrauenswürdigen Endpunkten für nur für Medienverkehr.

Für den HTTP-Verkehr müssen die Kunden eine der folgenden Möglichkeiten nutzen:

  • Domänennamen vonage und opentok auf die Whitelist setzen:

    • *.opentok.com
    • *.tokbox.com
    • *.vonage.com

  • Whitelist IP-Adressblöcke, die für die Vonage Video API bereitgestellt werden.

  • Verwenden Sie die Web-Proxy-Einstellungen auf den Clients, um den gesamten Vonage-HTTPS-Verkehr durch Ihre eigenen Ziele zu leiten. Siehe den Abschnitt Proxy-Anforderungen hier.

Wie wird der Medienpfad zwischen den verfügbaren TURN-Zielen ausgewählt. Wird dabei die Round-Trip-Latenz berücksichtigt, oder wird sie von der Reihenfolge beeinflusst, in der wir die Ziele auflisten, oder erfolgt sie zufällig?

Die Reihenfolge der TURN-Server wird nicht anhand der angegebenen Liste garantiert. Stattdessen wählt die ICE-Implementierung, wenn die Medien die ICE-Implementierung aus, welcher Kandidat/Server die beste Konnektivität aufweist und erfolgreich zuerst verhandelt.

Wenn die URL des TURN-Servers auf mehrere IP-Adressen verweist, wie wird dann der spezifische TURN-Server für die Sitzung ausgewählt? Ist dies zufällig?

Die meisten Implementierungen, einschließlich der in Chrome und Firefox verwendeten, nehmen die erste IP, die von der DNS-Abfrage zurückgegeben wird. Dies führt in der Regel zu einer zufälligen Auswahl in der Runde.

Wenn sowohl TCP- als auch UDP-TURN-Server bereitgestellt werden und erreichbar sind, ist es dann möglich, UDP-Ziele zu priorisieren und nur bei Bedarf auf TCP zurückzugreifen?

UDP-Relay-Kandidaten werden gegenüber TCP-Relay-Kandidaten bevorzugt, da diese Kandidaten eine eine niedrigere lokale Typpräferenz und damit eine niedrigere Priorität haben. Siehe RFC 8445 für Details. Die Reihenfolge der übergebenen ICE-Server spielt dabei keine Rolle.

Kann ein einzelner Client verschiedene Medienpfade für verschiedene Streams verwenden?

Ja, das ist das erwartete Verhalten, da Vonage jeden einzelnen Medienstrom separat behandelt.

Wie viel Kontrolle hat die konfigurierbare TURN-API über die Auswahl des Medienpfads?

Die Auswahl des Medienpfads wird von ICE (Interactive Connectivity Establishment) innerhalb von WebRTC gehandhabt, und wir haben keine Möglichkeit, dieses Verhalten zu ändern. Die konfigurierbare TURN-API hilft nur bei der Änderung der Liste von ICE-Servern, die der Client WebRTC zur Verfügung stellt, und beeinflusst den Auswahlprozess nicht.

Ist eine direkte Verbindung zum Vonage Media Server über UDP immer vorzuziehen?

Ja, eine direkte Verbindung zum Vonage Media Server ist immer vorzuziehen. Es wird auf die Verwendung von TURN umgeschaltet wenn die Verbindung zum Vonage Media Server nicht erfolgreich ist oder wenn die Option "Force TURN" in der in der konfigurierbaren TURN-API verwendet wird.

Kann ich mehrere TURN-Server desselben Typs zum Lastausgleich verwenden?

Dies wird nicht empfohlen, da der Client dann einen zufälligen Server auswählt, der sich während der Dauer der Verbindung ändern kann.

Wie kann ich die Last meines TURN-Servers ausbalancieren?

Bitte kontaktieren Sie uns für weitere Informationen.

Kann der TURN-Server Medien entschlüsseln?

Nein, der TURN-Server hat keinen Zugriff auf die SRTP-Schlüssel, die mit DTLS-SRTP ausgetauscht werden und nur den Endpunkten der Verbindung zur Verfügung stehen.

Was passiert, wenn ein TURN-Server während einer Sitzung abstürzt und wie man ihn wiederherstellen kann

Wenn ein TURN-Server abstürzt, während er benutzt wird, führt dies dazu, dass die Verbindung des Clients getrennt wird. Der Client versucht dann, die Verbindung mit einem ICE-Neustart wiederherzustellen.

Wie kann ich einen TURN-Server testen?

Sie können Ihren TURN-Server entweder mit Trickle Ice Testseite oder coturn turnutils_uclient.