SDK iOS

Le SDK iOS vous permet d'utiliser les sessions vidéo alimentées par l'API Video de Vonage dans les applications conçues pour les appareils iPad, iPhone et iPod touch.

La référence de l'API Video iOS SDK de Vonage se trouve à l'adresse suivante ici.

Toutes les Applications qui utilisent l'API Video de Vonage sont composées de deux parties :

  • Le côté client, qui utilise la fonction SDKs du client vidéo de Vonage et s'exécute dans le navigateur ou l'application mobile de l'utilisateur
  • Le côté serveur, qui utilise la fonction SDKs du serveur vidéo de Vonage et s'exécute sur votre serveur pour transmettre les informations d'authentification au client

Le Client SDK iOS fournit la plupart des fonctionnalités essentielles à votre application, notamment :

  • Connexion à la session
  • Publication de flux dans une session
  • S'abonner à des flux dans une session

Des SDK clients sont également disponibles pour le web, Android, iOS, Windows, macOS, Linux et React Native. Tous les SDK clients peuvent interagir les uns avec les autres.

Pour en savoir plus sur les principes de base des clients, des serveurs, des sessions, etc. Page des principes de base de Video API.

Remarques importantes

  • La version 2.35.1+ du SDK ne prend en charge qu'iOS 17 ou une version ultérieure.
  • La version 2.33.0+ du SDK prend en charge les Mac équipés d'un processeur Apple Silicon et fonctionnant sous macOS 14 ou une version ultérieure. Voir Support macOS Consultez la section ci-dessous pour connaître les particularités et les limitations propres à chaque plateforme.
  • Le partage d'écran sur macOS est limité à la fenêtre de l'application. - La capture du bureau complet n'est pas prise en charge. Voir ce problème connu pour plus de détails.
  • La version 2.25.1+ prend en charge Swift Package Manager. Depuis la version 2.35.1 et les versions ultérieures, la distribution via CocoaPods est obsolète et sera supprimée dans une prochaine version.
  • Modifications de la mise en réseau sous iOS 14 affectant les sessions relayées - voir la liste des problèmes connus dans les notes de mise à jour.
  • Problèmes liés à l'utilisation de Simulator pour prévisualiser votre application sur un Mac équipé d'une puce M1 - voir la liste des problèmes connus dans les notes de mise à jour.

Interopérabilité

Les applications développées à l'aide du SDK iOS Vonage 2.35.1 sont compatibles avec les applications Vonage développées à l'aide des Vonage Client SDK version 2.33 ou ultérieure :

  • OpenTok.js (Web)
  • SDK Android
  • SDK iOS
  • SDK Windows
  • SDK macOS
  • SDK Linux
  • SDK React Native

Installation

Le SDK iOS de Vonage Video prend en charge Swift Package Manager (SPM) comme méthode de distribution recommandée, disponible depuis la version 2.25.1. La distribution via CocoaPods via le VonageClientSDKVideo Le pod est également maintenu à des fins de compatibilité ascendante tant que la prise en charge de CocoaPods est disponible, mais il est en voie de dépréciation et sera finalement supprimé.

Recommandation : Les nouveaux projets doivent utiliser Swift Package Manager. Si vous utilisez actuellement CocoaPods, consultez la Migration depuis CocoaPods ci-dessous.

Swift Package Manager (recommandé)

Swift Package Manager est directement intégré à Xcode et ne nécessite aucun outil supplémentaire.

Dans Xcode :

  1. Ouvrez votre projet dans Xcode.
  2. Aller à Fichier > Ajouter des dépendances de paquets…
  3. Saisissez l'URL du dépôt suivante dans la barre de recherche : https://github.com/vonage/vonage-video-client-sdk-swift.git
  4. Sélectionnez la règle de version (par exemple : Jusqu'au prochain tournoi majeur) puis cliquez sur Ajouter un paquet.
  5. Sélectionnez l'option VonageClientSDKVidéo bibliothèque, puis cliquez sur Ajouter à la liste d'achats.

Les dépendances SPM sont résolues et téléchargées automatiquement lors de la compilation ou de l'ouverture du projet dans Xcode. Vous pouvez les consulter sous la rubrique Dépendances des paquets section dans le Navigateur de projet.

CocoaPods (obsolète)

⚠️ Avis de dépréciation : La distribution via CocoaPods est en voie d'abandon. Le VonageClientSDKVideo pod continuera d'être mis à jour tant que la prise en charge de CocoaPods sera disponible, mais nous vous recommandons vivement de migrer vers Swift Package Manager.

Ajoutez ce qui suit à votre Podfile:

target 'YourApp' do
pod 'VonageClientSDKVideo'
end

Ensuite, exécutez :

pod install

Ouvrez le fichier généré .xcworkspace fichier (pas .xcodeproj) pour compiler votre projet.

Migration depuis CocoaPods

Si votre projet utilise actuellement le OpenTok ou OTXCFramework Pour le pod CocoaPods, suivez ces étapes afin de migrer vers Swift Package Manager :

  1. Supprimez CocoaPods de votre projet :
pod deintegrate

Cela supprime toutes les phases de compilation et tous les paramètres CocoaPods de votre .xcodeproj.

  1. Supprimer les fichiers CocoaPods : Supprimer Podfile, Podfile.locket le Pods/ répertoire de votre dossier de projet. Supprimez également le fichier généré par CocoaPods .xcworkspace si vous n'en avez plus besoin.

  2. Ajoutez le SDK via SPM : Suivez les Gestionnaire de paquets Swift suivez les instructions ci-dessus pour ajouter https://github.com/vonage/vonage-video-client-sdk-swift.git en tant que dépendance du paquet.

  3. Mettez à jour vos importations : Si vous importiez OpenTok, le nom du module reste le même — aucune modification n'est nécessaire au niveau des importations.

  4. Compiler et vérifier : Ouvrez votre .xcodeproj directement dans Xcode (sans .xcworkspace nécessaires pour les projets SPM uniquement) et lancez la compilation pour vérifier que tout fonctionne correctement.

Configuration requise

La version actuelle du SDK iOS (2.35.1+) est prise en charge sous iOS 17 ou une version ultérieure.

Le SDK iOS est pris en charge par les connexions Wi-Fi, 4G/LTE et 5G.

La version actuelle du SDK iOS nécessite Xcode 10 ou une version ultérieure.

Pour une diffusion vidéo fiable, assurez-vous que votre appareil répond aux spécifications recommandées :

  • CPU : Apple A12 Bionic ou plus récent.
  • MÉMOIRE VIVE : Au moins 4 Go de RAM pour les appels de groupe et le multitâche.
  • Écran : 5.4"+ pour iPhone, 10.2"+ pour iPad.
  • Capacité de la batterie : 3000+ mAh pour l'iPhone, 7000+ mAh pour l'iPad.
  • Réseau : Connectivité internet fiable ; fonctionne sur Wi-Fi ou cellulaire.

Ces recommandations garantissent une lecture stable, une utilisation réduite de l'unité centrale et des performances fluides lors de la diffusion de vidéos.

Exemples d'appareils : iPhone XS ou plus récent (2018+), iPad Pro (toute génération), iPad Air 3 ou plus récent, iPad mini 5 ou plus récent.

Apprendre à construire

La meilleure façon d'apprendre à utiliser le SDK iOS est de suivre la procédure suivante Tutoriel de base sur le chat vidéo.

Une fois que vous avez compris les bases de la création avec le SDK iOS de Vonage, vous pouvez obtenir des informations plus détaillées et apprendre à personnaliser votre application avec le logiciel de gestion de l'application iOS de Vonage. Guides du développeur Vonage. Pour étudier des classes et des méthodes spécifiques de l'API, voir la page Guide de référence de l'API du SDK iOS de Vonage.

Utiliser le SDK

Le SDK iOS nécessite les frameworks et bibliothèques suivants :

  • AudioToolbox.framework
  • AVFoundation.framework
  • CoreGraphics.framework
  • CoreMedia.framework
  • CoreTelephony.framework
  • CoreVideo.framework
  • Foundation.framework
  • GLKit.framework
  • libc++.tbd (libc++.dylib avant Xcode 7)
  • libsqlite3++.tbd (libsqlite3.dylib avant Xcode 7)
  • Métal.cadre
  • MetalKit.framework
  • MetalPerformanceShaders.framework
  • OpenGLES.framework
  • QuartzCore.framework
  • SystemConfiguration.framework
  • UIKit.framework
  • VideoToolbox.framework

Utiliser le -force_load pour charger les bibliothèques spécifiques qui le nécessitent, ceci est géré pour vous si vous ajoutez le SDK via CocoaPods ou Swift Package Manager.

Le SDK iOS est lié à la bibliothèque standard libc++. Si une autre bibliothèque liée à la bibliothèque standard libc++ a été compilée dans une version de Xcode antérieure à la version 6.0.0, elle peut entraîner des erreurs de segmentation à l'exécution lorsqu'elle est utilisée avec le SDK iOS. Les bibliothèques incompatibles connues incluent, mais ne sont pas limitées à, Firebase (versions antérieures à 2.1.2 -- voir https://code.google.com/p/webrtc/issues/detail?id=3992 et Google Maps (versions antérieures à 1.9.0). Pour résoudre ce problème, téléchargez une version de l'autre bibliothèque qui a été compilée à l'aide de Xcode 6.0.0 ou d'une version ultérieure. Voir l'article notes de mise à jour pour obtenir des informations sur la dernière version du SDK et une liste des problèmes connus.

Pour accéder à l'appareil photo et au microphone, iOS 10 exige que vous définissiez des valeurs pour le paramètre NSCameraUsageDescription et NSMicrophoneUsageDescription dans le fichier Info.plist. Elles définissent les chaînes qui apparaissent dans le programme d'installation de l'application pour informer l'utilisateur de la raison pour laquelle votre application utilise la caméra et le microphone.

Pour plus d'informations, voir la documentation d'Apple sur les clés Cocoa.

Voir le présent document pour obtenir des informations sur l'utilisation du SDK dans les applications fonctionnant en arrière-plan.

Paramètres de la charte de confidentialité

La version 2.25.5 et les versions plus récentes du SDK prennent en charge l'option manifeste de confidentialité requis par l'App Store d'Apple. En utilisant ces versions du SDK, les paramètres de confidentialité requis sont automatiquement ajoutés lorsque vous créer le rapport de confidentialité de votre application. Si vous devez utiliser une version plus ancienne du SDK, vous pouvez ajouter manuellement les paramètres de confidentialité requis en vous basant sur les paramètres de cette page. fichier dans le fichier manifeste de confidentialité de votre application.

Exécution en arrière-plan

Voir Gestion de l'état d'arrière-plan.

CallKit

CallKit est un framework qui permet aux apps iOS d'améliorer leur intégration avec le système d'exploitation, en leur permettant de :

  • Notifier les appels entrants ou sortants au système d'exploitation
  • Lancer l'application avec une notification VoIP push (uniquement si vous souhaitez afficher l'interface utilisateur de l'appel entrant)
  • Gérer le routage audio
  • Coordonner les sessions audio entre toutes les applications en cours
  • Augmenter les niveaux de sortie audio
  • Afficher les contrôles d'appel dans une notification et une interface utilisateur native

La vidéo Vonage propose deux façons de s'intégrer à CallKit :

  1. Mettre en place un CustomAudioDevice qui contrôle le AudioSession activations. Voir aussi cet échantillon.
  2. Activez le mode services d'appel en utilisant OTAudioDeviceManager.currentAudioSessionManager(). L'instance renvoyée par le gestionnaire de session audio doit être utilisée pour configurer la session audio et notifier au SDK les activations et désactivations de la session audio. Voir cet échantillon.

Si votre application a besoin d'être notifiée pour des événements d'application, tels que des appels entrants, le développeur est responsable de sa mise en œuvre. Nous recommandons d'utiliser la méthode PushKit cadre et Notifications push VoIP. A titre de référence, voir cet échantillon.

L'intégration native de Vonage Video nécessite que le développeur active le mode services d'appel dès le lancement de l'application. Les notifications push VoIP nécessitent un appel à CXProvider.reportNewIncomingCall dans les 3 secondes, faute de quoi l'application peut se bloquer. Dans ce laps de temps, l'application doit configurer la prise en charge du SDK CallKit avant que la fonction CXAnswerCallAction est exécuté.

Pour activer le mode "services d'appel", appelez le code suivant dans la page d'accueil de votre application application:didFinishLaunchingWithOptions: méthode.

let sessionManager = OTAudioDeviceManager.currentSessionManager()
sessionManager?.enableCallingServicesMode()

Configurer le AVAudioSession dans le CXStartCallAction ou CXAnswerCallAction CXProvider callbacks. Utilisez le mode chat vidéo pour les appels vidéo, ou le mode chat vocal pour les appels audio uniquement.

sessionManager?.preconfigureAudioSessionForCall(withMode: .videoChat)
sessionManager?.preconfigureAudioSessionForCall(withMode: .voiceChat)

Notifie au gestionnaire de session les activations et désactivations de sessions audio.

func provider(_ provider: CXProvider, didActivate audioSession: AVAudioSession) {
   sessionManager?.audioSessionDidActivate(audioSession)
}
func provider(_ provider: CXProvider, didDeactivate audioSession: AVAudioSession) {
   sessionManager?.audioSessionDidDeactivate(audioSession)
}

Vérifier le Documentation pour les développeurs CallKit pour plus d'informations.

Modifications réseau apportées par iOS 14 ayant une incidence sur les sessions relayées

Avec iOS 14, Apple introduit la confidentialité du réseau local (voir cette vidéo).

À partir d'iOS 14, le système d'exploitation demandera l'autorisation de l'utilisateur lorsqu'une application tentera de s'abonner à des clients situés sur le même réseau local dans un session relayée. Le texte par défaut de la notification indique que l'application « souhaite rechercher des appareils sur votre réseau local et s'y connecter ».

Lors d'une session relayée, la Video API vonage utilise le réseau local pour détecter les participants à la visioconférence présents sur ce réseau et s'y connecter, dans la mesure du possible. Si les clients ne parviennent pas à se connecter au réseau local, l'application utilise le serveur TURN d'OpenTok pour relayer les flux audio et vidéo.

Si l'utilisateur refuse l'autorisation, la tentative d'abonnement peut échouer si le client ne parvient pas à se connecter au serveur TURN d'OpenTok. Dans ce cas, une fois l'autorisation refusée, toute tentative ultérieure d'abonnement pour des clients situés sur le même réseau échouera également, à moins que l'utilisateur ne modifie l'autorisation dans les Réglages. Malheureusement, iOS ne fournit pas d’API permettant à une application de déterminer si l’utilisateur a accepté ou refusé cette autorisation.

Il est important de noter que cela ne s'applique pas aux sessions vidéo qui utilisent le Routeur média, car les données multimédias sont transmises via Internet plutôt que via le réseau local.

Si votre application utilise une session relayée, nous vous recommandons d'ajouter une chaîne de texte personnalisée et descriptive afin d'expliquer à l'utilisateur pourquoi l'application a besoin de cette autorisation :

  1. Dans Xcode, ouvrez le fichier info.plist de votre application.

  2. Dans l'éditeur info.plist, cliquez avec le bouton droit de la souris sur la colonne de gauche et sélectionnez Ajouter une rangée (ou cliquez sur +) pour ajouter un paramètre pour Vie privée - Utilisation du réseau local Description.

  3. Modifiez la valeur de cette chaîne pour décrire comment votre application utilise cette autorisation. Par exemple, ajoutez : « Cette application utilise le réseau local pour détecter les participants à la visioconférence se trouvant sur le même réseau et se connecter à eux lorsque cela est possible. »

L'invite adressée à l'utilisateur comprendra cette description.

Pour les applications qui ne peuvent pas utiliser de sessions acheminées et pour lesquelles vous ne souhaitez pas que l'utilisateur soit invité à autoriser l'accès au réseau local, vous pouvez utiliser l'une des options décrites dans les sections suivantes.

Sauter les vérifications du réseau local pour établir la connectivité des médias

Vous pouvez régler la OTSessionICEConfig.filterOutLanCandidates propriété permettant d'empêcher l'application d'utiliser le réseau local pour établir une connexion, comme dans le code suivant.

let settings = OTSessionSettings()
let myICEServerConfiguration = OTSessionICEConfig()
myICEServerConfiguration.filterOutLanCandidates = true
settings.iceConfig = myICEServerConfiguration
let session = OTSession(applicationId: applicationId, sessionId: sessionId, delegate: self,
                        settings: settings)

OTSessionSettings *settings = [[OTSessionSettings alloc] init];
OTSessionICEConfig *myICEServerConfiguration = [[OTSessionICEConfig alloc] init];
myICEServerConfiguration.filterOutLanCandidates = YES;
settings.iceConfig = myICEServerConfiguration;
session = [[OTSession alloc] initWithApiKey:kApplicationId
                                   sessionId:kSessionId
                                    delegate:self settings:settings];

Remarque : Les OTSessionICEConfig.filterOutLanCandidates est disponible dans la version 2.30.0 du SDK iOS de Vonage Video et dans les versions ultérieures.

Utiliser les serveurs TURN

Vous pouvez régler la OTSessionICEConfig.transportPolicy pour forcer l'application à utiliser des serveurs TURN afin d'établir la connexion, comme dans le code suivant.

let settings = OTSessionSettings()
let myICEServerConfiguration = OTSessionICEConfig()
myICEServerConfiguration.transportPolicy = .relay
settings.iceConfig = myICEServerConfiguration
let session = OTSession(applicationId: applicationId, sessionId: sessionId, delegate: self,
                        settings: settings)

OTSessionSettings *settings = [[OTSessionSettings alloc] init];
OTSessionICEConfig *myICEServerConfiguration = [[OTSessionICEConfig alloc] init];
myICEServerConfiguration.transportPolicy = OTSessionICETransportRelay;
settings.iceConfig = myICEServerConfiguration;
session = [[OTSession alloc] initWithApiKey:kApplicationId
                                   sessionId:kSessionId
                                    delegate:self settings:settings];

Support macOS

Le SDK iOS 2.33.0+ est pris en charge sur les Mac Apple siliconés (M1, M2, M3 et ultérieurs) fonctionnant sous macOS 14 ou ultérieur. Sur macOS, le SDK offre la plupart des fonctionnalités disponibles sur les appareils iOS, bien qu'il y ait quelques différences et limitations spécifiques à la plateforme à garder à l'esprit.

Comportement de l'appareil photo sous macOS

Les appareils macOS disposent généralement d'une seule caméra intégrée (la caméra FaceTime), qui est toujours désignée comme la caméra frontale (AVCaptureDevicePositionFront). Les caméras externes connectées au Mac sont également traitées comme des caméras frontales.

Considérations importantes :

  • Contrairement aux appareils iOS, les Mac n'ont pas de notion de "caméra arrière"
  • Les cameraPosition la propriété se résoudra toujours à la caméra frontale sur macOS
  • Pour passer d'une caméra à l'autre (par exemple, caméra intégrée ou externe) sous macOS, vous pouvez mettre en œuvre un capteur vidéo personnalisé. Pour plus d'informations, voir la page Capture vidéo personnalisée guide.

Traitement des rotations

Les appareils macOS ne prennent pas en charge la rotation automatique de l'orientation comme les appareils mobiles iOS.

  • La vidéo est toujours publiée en orientation paysage
  • Les événements de rotation des appareils ne se produisent pas sous macOS
  • Les applications doivent gérer l'orientation manuellement si des ajustements spécifiques de la mise en page sont nécessaires.

Limitation de la torche (lampe de poche)

La fonction torche de l'appareil photo n'est pas disponible sur macOS.

  • Réglage de la cameraTorch à la propriété true n'aura aucun effet sur macOS
  • Les appareils photo Mac (intégrés ou externes) ne prennent pas en charge la fonctionnalité torche/flashlight.
  • Cette fonction est spécifique aux appareils mobiles iOS

Échantillons de code

Pour obtenir des échantillons, visitez notre dépôt de l'application d'exemple sur GitHub.

Documentation et informations complémentaires

Vous trouverez une documentation détaillée de chaque méthode iOS dans la rubrique guide de référence.

Pour une liste des nouvelles fonctionnalités et des problèmes connus, voir la page notes de mise à jour.