Servidores TURN configuráveis

Visão geral

Esse recurso está disponível como um recurso adicional.

Client SDK: Observe que o seu ID do aplicativo é o seu Chave de API.

É possível personalizar o uso do servidor TURN para cada cliente na sessão das seguintes maneiras:

Você pode adicionar uma lista dos seus próprios servidores TURN que o cliente utilizará.
Você pode decidir se o cliente deve usar exclusivamente seus servidores TURN ou utilizá-los além dos servidores TURN da Vonage

Adicionar seus próprios servidores TURN pode ajudar os usuários a se conectarem em ambientes de rede restritivos, nos quais os servidores TURN da Vonage possam estar bloqueados.

Se você optar por substituir os servidores TURN da Vonage e usar apenas seus próprios servidores TURN, poderá garantir que os fluxos de mídia nunca saiam da sua rede.

Você pode adicionar seus próprios servidores TURN para cada cliente que se conectar à sessão, usando o OpenTok.js (para clientes web), o SDK para iOS ou o SDK para Android. A API do servidor TURN personalizado foi adicionada na versão 2.13.0 desses Client SDKs.

Há também um Proxy de IP recurso adicional que permite que você use seu próprio servidor proxy para rotear não relacionado à mídia tráfego — como chamadas à Video API, conexões WebSocket e tráfego de logs.

OpenTok.js (v2.13.0+)

O options parâmetro do OT.initSession() O método inclui um recurso não documentado iceConfig propriedade. Essa propriedade inclui as seguintes propriedades:

includeServers (String) - Defina isso como 'custom' e o cliente utilizará apenas os servidores TURN personalizados que você fornecer no customServers matriz. Defina isso como 'all' (a configuração padrão) e o cliente utilizará tanto os servidores TURN personalizados que você fornecer quanto os servidores TURN da Vonage.
transportPolicy (String) - Defina isso como 'all' (padrão) e o cliente utilizará todos os tipos de transporte ICE (como host, srflx e TURN) para estabelecer a conectividade de mídia. Defina isso como 'relay' para forçar sempre a conectividade por meio do TURN e ignorar todos os outros candidatos a ICE .
customServers (Matriz) - Defina aqui uma matriz de objetos que definam seus servidores TURN personalizados. Cada objeto corresponde a um servidor TURN personalizado e inclui as seguintes propriedades:
- urls (String ou matriz de strings) — Uma string ou uma matriz de strings, em que cada string é uma URL compatível com o servidor TURN (podendo ser apenas uma URL).
- username (String) - O nome de usuário do servidor TURN definido neste objeto.
- credential (String) - A string de credenciais para o servidor TURN definido neste objeto.

Observação: Para que o cliente utilize apenas os servidores TURN que você especificar (e não utilize os servidores TURN da Vonage): defina o includeServers propriedade para 'custom', defina o transportPolicy propriedade para 'relay', e definir o customServers propriedade para listar seus servidores TURN.

Para atualizar dinamicamente as credenciais personalizadas do TURN, use o Session.setIceConfig() método.

O exemplo a seguir mostra como configurar servidores TURN para o cliente:

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',
      },
    ],
  },
});

SDK do Android

O Session.Builder A classe inclui dois métodos para configurar o uso do servidor TURN pelo cliente:

Session.Builder.setCustomIceServers() - Chame este método para adicionar uma lista de servidores TURN personalizados para o cliente.
Session.Builder.setIceRouting() - Chame este método para adicionar opções de limitação do ICE para o cliente.

Além dos dois novos métodos, duas novas enums definem as opções do servidor TURN:

IncludeServers - Inclui opções para usar apenas os servidores personalizados ou tanto os servidores da Vonage quanto os servidores personalizados.
TransportPolicy - Descreve o método de roteamento a ser utilizado.

Observação: Para que o cliente utilize apenas os servidores TURN que você especificar (e não utilize os servidores TURN da Vonage), chame os seguintes métodos do objeto Session.Builder que você usa para criar o objeto Session:

setCustomIceServers() - Passe uma lista de objetos IceServer (correspondentes aos seus servidores TURN personalizados) como o serverList parâmetro e passar IncludeServers.TURN como o config parâmetro.
setIceRouting() - Passar para TransportPolicy.Relay.

O exemplo a seguir mostra como configurar servidores TURN para o cliente:

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);

SDK do iOS

Ao inicializar um objeto OTSession, defina o OTSessionSettings.iceConfig propriedade para definir uma configuração personalizada do servidor TURN para o cliente. A classe OTSessionICEConfig define o OTSessionSettings.iceConfig propriedade.

Observação: Para que o cliente utilize apenas os servidores TURN que você especificar (e não utilize os servidores TURN da Vonage), chame a função [OTSessionSettings addICEServerWithURL:] método do objeto OTSessionSettings que você usa para criar o objeto OTSession. Em seguida, defina as seguintes propriedades do objeto OTSessionSettings:

includeServers - Defina esse parâmetro como OTSessionICEIncludeServersCustom.
transportPolicy - Defina este valor como OTSessionICETransportRelay.

Você pode definir o OTSessionICEConfig.filterOutLanCandidates propriedade para impedir a inscrição de clientes na mesma rede local em sessões retransmitidas, o que faz com que o aplicativo solicite permissão ao usuário no iOS 14 e versões posteriores. Observe que esse recurso não requer o complemento TURN configurável. Para mais informações, consulte esse assunto.

O exemplo a seguir mostra como configurar servidores TURN para o cliente:

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];

SDK do Windows

Use a classe IceConfig para definir a configuração personalizada do ICE a ser utilizada pelo cliente.

O IceConfig() O método construtor inclui os seguintes parâmetros:

customIceServers -- Defina aqui uma lista de objetos IceServer, representando servidores TURN personalizados a serem utilizados pelo cliente. Para cada IceServer, você deve definir a URL, o nome de usuário e a string de credenciais do servidor TURN personalizado
transportPolicy -- Defina isso como um valor no ICETransport enum:
- All -- O cliente utilizará todos os tipos de candidatos ICE (como host, srflx e relay) para estabelecer a conectividade de mídia.
- Relayed -- O cliente sempre forçará a conectividade por meio do TURN e ignorará todos os outros candidatos a ICE.
includeServers -- Defina isso como um valor no IncludeServers enum:
- All -- O cliente utilizará os servidores TURN da Vonage, além dos servidores TURN personalizados que você fornecer.
- Custom -- O cliente utilizará apenas os servidores TURN personalizados que você fornecer.

A classe Session.Builder inclui um IceConfig propriedade. Defina-a como um objeto IceConfig ao criar o objeto Session. O exemplo a seguir mostra como configurar servidores TURN para o cliente:

List<IceServer> iceServers = new List<IceServer>() {
  new IceServer(
    "turn:123.124.125.126:3478?transport=udp", "webrtc", "fo0Bar1"
  )
};
IceConfig iceConfig = new IceConfig(
  iceServers,
  ICETransport.Relayed,
  ICEIncludeServers.Custom
);
session = new Session.Builder(context, applicationId, sessionId){
  IceConfig = iceConfig
}.Build();

SDK do macOS

O tipo otc_custom_ice_config define uma estrutura que inclui os seguintes membros:

num_ice_servers -- O número de servidores ICE
ice_url -- Uma matriz de strings que especifica as URLs do seu servidor ICE.
ice_user -- Uma matriz de strings que especifica os nomes de usuário para os servidores TURN.
ice_credential -- Uma matriz de strings que especifica as credenciais para os servidores TURN. Chame a função otc_session_settings_set_custom_ice_config() função e passar o otc_custom_ice_config exemplo:

otc_session_settings_set_custom_ice_config(session_settings,
                                           &ice_config);

O exemplo a seguir mostra como configurar servidores TURN para o cliente:

// 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);

SDK do Linux

O tipo otc_custom_ice_config define uma estrutura que inclui os seguintes membros:

num_ice_servers -- O número de servidores ICE
ice_url -- Uma matriz de strings que especifica as URLs do seu servidor ICE.
ice_user -- Uma matriz de strings que especifica os nomes de usuário para os servidores TURN.
ice_credential -- Uma matriz de strings que especifica as credenciais para os servidores TURN.

Ligue para o otc_session_settings_set_custom_ice_config() função e passar o otc_custom_ice_config exemplo:

otc_session_settings_set_custom_ice_config(session_settings,
                                           &ice_config);

O exemplo a seguir mostra como configurar servidores TURN para o cliente:

// 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);

SDK do React Native

O options adereço do OTSession O componente inclui um iceConfig propriedade. Esse objeto inclui as seguintes propriedades:

includeServers (String) — Defina este valor como 'custom' e o cliente utilizará apenas os servidores TURN personalizados que você fornecer no customServers matriz. Defina isso como 'all' (padrão) e o cliente utilizará tanto os servidores TURN personalizados que você fornecer quanto os servidores TURN da OpenTok.
transportPolicy (String) — Defina este valor como 'all' (padrão) e o cliente utilizará todos os tipos de transporte ICE (como host, srflx e TURN) para estabelecer a conectividade de mídia. Defina isso como 'relay' para forçar sempre a conectividade por meio do TURN e ignorar todos os outros candidatos a ICE .
customServers (Matriz) — Defina isso como uma matriz de objetos que definam seus servidores TURN personalizados. Cada objeto corresponde a um servidor TURN personalizado e inclui as seguintes propriedades:
- urls (String ou matriz de strings) — Uma string ou uma matriz de strings, em que cada string é uma URL compatível com o servidor TURN (podendo ser apenas uma URL).
- username (String) — O nome de usuário do servidor TURN definido neste objeto.
- credential (String) — A string de credenciais para o servidor TURN definido neste objeto.

Observação: Para que o cliente utilize apenas os servidores TURN que você especificar (e não utilize os servidores TURN da OpenTok): defina o includeServers propriedade para 'custom', defina o transportPolicy propriedade para 'relay', e definir o customServers propriedade para listar seus servidores TURN.

O exemplo a seguir mostra como configurar servidores TURN para o cliente:

<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>

Problema conhecido

Se você configurar um cliente para sempre usar servidores TURN em um sessão retransmitida, ele não poderá se inscrever em seus próprios streams (os streams que ele publica).

Perguntas frequentes

A API TURN configurável resolve o problema do tráfego HTTP?

Não. O TURN configurável dissipa as preocupações dos clientes quanto à conexão com terminais confiáveis exclusivamente para o tráfego de mídia.

Para o tráfego HTTP, os clientes deverão realizar uma das seguintes ações:

Adicione os nomes de domínio da Vonage e da Opentok à lista de permissões:
- *.opentok.com
- *.tokbox.com
- *.vonage.com
Blocos de endereços IP incluídos na lista de permissões fornecida para a Video API da Vonage.
Utilize as configurações de proxy da web nos clientes para redirecionar todo o tráfego HTTPS da Vonage através de seus próprios servidores de destino. Consulte a seção “Requisitos de proxy” aqui.

Como o caminho de mídia é selecionado entre os destinos TURN disponíveis? Ele leva em conta a latência de ida e volta, é influenciado pela ordem em que listamos os destinos ou é aleatório?

A ordem dos servidores TURN não é garantida com base na lista fornecida. Em vez disso, quando a transmissão de mídia começa, a implementação do ICE seleciona o candidato/servidor que apresentar a melhor conectividade e que tiver negociado com sucesso primeiro.

Se a URL do servidor TURN estiver associada a vários endereços IP, como é selecionado o servidor TURN específico para a sessão? Isso ocorre de forma aleatória?

A maioria das implementações, incluindo as utilizadas no Chrome e no Firefox, utiliza o primeiro endereço IP retornado pela consulta ao DNS. Isso geralmente resulta em uma seleção aleatória do tipo round-robin.

Se houver servidores TURN tanto TCP quanto UDP disponíveis e acessíveis, é possível priorizar os destinos UDP e recorrer ao TCP apenas se necessário?

Os candidatos a retransmissão UDP terão preferência sobre os candidatos a retransmissão TCP, uma vez que esses candidatos têm uma preferência de tipo local menor e, portanto, uma prioridade menor. Consulte RFC 8445 para mais detalhes. A ordem em que os servidores ICE são passados não influencia isso.

Um único cliente pode usar caminhos de mídia diferentes para transmissões diferentes?

Sim, esse é o comportamento esperado, pois a Vonage trata cada fluxo de mídia individualmente.

Qual é o grau de controle que a API TURN configurável exerce sobre a seleção do caminho de mídia?

A seleção do caminho de mídia é feita pelo ICE (Interactive Connectivity Establishment) dentro do WebRTC, e não temos como modificar esse comportamento. A API Configurable TURN apenas permite modificar a lista de servidores ICE fornecida pelo cliente ao WebRTC e não influencia o processo de seleção.

A conexão direta com o Vonage Media Server via UDP é sempre a preferida?

Sim, a conexão direta com o Vonage Media Server é sempre a preferida. O sistema recorre ao TURN caso a conexão com o Vonage Media Server não seja bem-sucedida ou se a opção “Forçar TURN” for utilizada na API TURN configurável.

Posso usar vários servidores TURN do mesmo tipo para balanceamento de carga?

Isso não é recomendado, pois fará com que o cliente escolha um servidor aleatório, e esse servidor pode mudar ao longo da conexão.

Como faço para distribuir a carga na minha implantação personalizada do servidor TURN?

Entre em contato conosco para obter mais informações.

O servidor TURN é capaz de descriptografar arquivos de mídia?

Não, o servidor TURN não tem acesso às chaves SRTP que são trocadas por meio do DTLS-SRTP e que estão disponíveis apenas para os terminais da conexão.

O que acontece se um servidor TURN travar durante uma sessão e como recuperar o sistema

Se um servidor TURN travar enquanto estiver em uso, isso fará com que a conexão do cliente seja interrompida. O cliente tentará restabelecer a conexão por meio de um reinício ICE.

Como posso testar um servidor TURN?

Você pode testar seu servidor TURN usando Página de teste do Trickle Ice ou coturn turnutils_uclient.