WebRTC SDK for iOS - Kinesis Video Streams
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

WebRTC SDK for iOS

The following step-by-step instructions describe how to download, build, and run the Kinesis Video Streams WebRTC SDK in iOS and its corresponding samples.

Download the WebRTC SDK in iOS

To download the WebRTC SDK in iOS, run the following command:

$ git clone https://github.com/awslabs/amazon-kinesis-video-streams-webrtc-sdk-ios.git

Build the WebRTC SDK in iOS

Complete the following steps:

  1. Import the iOS WebRTC SDK into the XCode integrated development environment (IDE) on an iOS computer by opening KinesisVideoWebRTCDemoApp.xcworkspace (path: amazon-kinesis-video-streams-webrtc-sdk-ios/Swift/AWSKinesisVideoWebRTCDemoApp.xcworkspace).

  2. If you open the project for the first time, it automatically builds. If not, initiate a build.

    You might see the following error:

    error: The sandbox is not in sync with the Podfile.lock. Run 'pod install' or update your CocoaPods installation.

    If you see this, do the following:

    1. Change your current working directory to amazon-kinesis-video-streams-webrtc-sdk-ios/Swift and run the following in the command line:

      pod cache clean --all pod install
    2. Change your current working directory to amazon-kinesis-video-streams-webrtc-sdk-ios and run the following at the command line:

      $ git checkout Swift/Pods/AWSCore/AWSCore/Service/AWSService.m
    3. Build again.

  3. Configure Amazon Cognito (user pool and identity pool) settings. For details steps, see Configure Amazon Cognito for the iOS WebRTC SDK. This generates authentication and authorization settings required to build the iOS WebRTC SDK.

  4. In your IDE, open the awsconfiguration.json file (from /Swift/KVSiOSApp). The file looks like the following:

    { "Version": "1.0", "CredentialsProvider": { "CognitoIdentity": { "Default": { "PoolId": "REPLACEME", "Region": "REPLACEME" } } }, "IdentityManager": { "Default": {} }, "CognitoUserPool": { "Default": { "AppClientSecret": "REPLACEME", "AppClientId": "REPLACEME", "PoolId": "REPLACEME", "Region": "REPLACEME" } } }

    Update awsconfiguration.json with the values generated by running the steps in Configure Amazon Cognito for the Android WebRTC SDK.

  5. In your IDE, open the Constants.swift file (from /Swift/KVSiOSApp). The file looks like the following:

    import Foundation import AWSCognitoIdentityProvider let CognitoIdentityUserPoolRegion = AWSRegionType.USWest2 let CognitoIdentityUserPoolId = "REPLACEME" let CognitoIdentityUserPoolAppClientId = "REPLACEME" let CognitoIdentityUserPoolAppClientSecret = "REPLACEME" let AWSCognitoUserPoolsSignInProviderKey = "UserPool" let CognitoIdentityPoolID = "REPLACEME" let AWSKinesisVideoEndpoint = "https://kinesisvideo.us-west-2.amazonaws.com" let AWSKinesisVideoKey = "kinesisvideo" let VideoProtocols = ["WSS", "HTTPS"] let ConnectAsMaster = "connect-as-master" let ConnectAsViewer = "connect-as-viewer" let MasterRole = "MASTER" let ViewerRole = "VIEWER" let ClientID = "ConsumerViewer"

    Update Constants.swift with the values generated by running the steps in Configure Amazon Cognito for the Android WebRTC SDK.

  6. Make sure your iOS device is connected to the Mac computer where you're running XCode. In XCode, select the connected device and then build and run the WebRTC iOS SDK.

    This step installs an app called AWSKinesisVideoWebRTCDemoApp on your iOS device. Using this app, you can verify live WebRTC audio/video streaming between mobile, web and IoT device clients.

Run the iOS Sample Application

Complete the following steps:

  1. On your iOS device, open AWSKinesisVideoWebRTCDemoApp and log in using either a new (by creating it first) or an existing Amazon Cognito account.

  2. In AWSKinesisVideoWebRTCDemoApp, navigate to the Channel Configuration page and either create a new signaling channel or choose an existing one.

    Note

    Currently, using the sample application in this SDK, you can only run one signalling channel in AWSKinesisVideoWebRTCDemoApp.

  3. (Optional) Choose a unique Client Id if you want to connect to this channel as a viewer. Client Id is required only if multiple viewers are connected to a channel. This helps channel's master identify respective viewers.

  4. Choose the Amazon Web Services Region and whether you want to send audio or video data, or both.

  5. To verify peer-to-peer streaming, do any of the following:

    Note

    Ensure that you specify the same signaling channel name, Amazon region, viewer ID, and the Amazon account ID on all clients that you're using in this demo.

    • Peer-to-peer streaming between two iOS devices: master and viewer

      • Using procedures above, download, build, and run the iOS WebRTC SDK on two iOS devices.

      • Open AWSKinesisVideoWebRTCDemoApp on one iOS device in master mode (choose START MASTER) to start a new session (signaling channel).

        Note

        Currently, there can only be one master for any given signaling channel.

      • Open AWSKinesisVideoWebRTCDemoApp on your second iOS device in viewer mode to connect to the signaling channel (session) started in the step above (choose START VIEWER).

        Verify that the viewer can see master's audio/video data.

    • Peer-to-peer streaming between the embedded SDK master and an iOS device viewer

      • Download, build, and run the WebRTC SDK in C for Embedded Devices in master mode on a camera device.

      • Using procedures above, download, build, and run the iOS WebRTC SDK on an iOS device. Open AWSKinesisVideoWebRTCDemoApp on this iOS device in viewer mode and verify that the iOS viewer can see the embedded SDK master's audio/video data.

    • Peer-to-peer streaming between iOS device as master and web browser as viewer

      • Using procedures above, download, build, and run the iOS WebRTC SDK on an iOS device. Open AWSKinesisVideoWebRTCDemoApp on this iOS device in master mode (choose START MASTER) to start a new session (signaling channel).

      • Download, build, and run the WebRTC SDK in JavaScript for Web Applications as viewer and verify that the JavaScript viewer can see the Android master's audio/video.

Configure Amazon Cognito for the iOS WebRTC SDK

Prerequisites

  • We recommend XCode for examining, editing, and running the application code. We recommend the latest version.

  • In the sample code, you provide Amazon Cognito credentials.

Follow these procedures to set up an Amazon Cognito user pool and identity pool.

Set up a user pool

To set up a user pool
  1. Sign in to the Amazon Cognito console and verify the region is correct.

  2. In the navigation on the left choose User pools.

  3. In the User pools section, choose Create user pool.

  4. Complete the following sections:

    1. Step 1: Configure sign-in experience - In the Cognito user pool sign-in options section, select the appropriate options.

      Select Next.

    2. Step 2: Configure security requirements - Select the appropriate options.

      Select Next.

    3. Step 3: Configure sign-up experience - Select the appropriate options.

      Select Next.

    4. Step 4: Configure message delivery - Select the appropriate options.

      In the IAM role selection field, select an existing role or create a new role.

      Select Next.

    5. Step 5: Integrate your app - Select the appropriate options.

      In the Initial app client field, choose Confidential client.

      Select Next.

    6. Step 6: Review and create - Review your selections from the previous sections, then choose Create user pool.

  5. On the User pools page, select the pool that you just created.

    Copy the User pool ID and make note of this for later. In the awsconfiguration.json file, this is CognitoUserPool.Default.PoolId.

  6. Select the App integration tab and go to the bottom of the page.

  7. In the App client list section, choose the App client name you just created.

    Copy the Client ID and make note of this for later. In the awsconfiguration.json file, this is CognitoUserPool.Default.AppClientId.

  8. Show the Client secret and make note of this for later. In the awsconfiguration.json file, this is CognitoUserPool.Default.AppClientSecret.

Set up an identity pool

To set up an identity pool
  1. Sign in to the Amazon Cognito console and verify the region is correct.

  2. In the navigation on the left choose Identity pools.

  3. Choose Create identity pool.

  4. Configure the identity pool.

    1. Step 1: Configure identity pool trust - Complete the following sections:

      • User access - Select Authenticated access

      • Authenticated identity sources - Select Amazon Cognito user pool

      Select Next.

    2. Step 2: Configure permissions - In the Authenticated role section, complete the following fields:

      • IAM role - Select Create a new IAM role

      • IAM role name - Enter a name and make note of it for a later step.

      Select Next.

    3. Step 3: Connect identity providers - In the User pool details section complete the following fields:

      • User pool ID - Select the user pool you created earlier.

      • App client ID - Select the app client ID you created earlier.

      Select Next.

    4. Step 4: Configure properties - Type a name in the Identity pool name field.

      Select Next.

    5. Step 5: Review and create - Review your selections in each of the sections, then select Create identity pool.

  5. On the Identity pools page, select your new identity pool.

    Copy the Identity pool ID and make note of this for later. In the awsconfiguration.json file, this is CredentialsProvider.CognitoIdentity.Default.PoolId.

  6. Update the permissions for the IAM role.

    1. Sign in to the Amazon Web Services Management Console and open the IAM console at https://console.amazonaws.cn/iam/.

    2. In the navigation on the left, choose Roles.

    3. Find and select the role you created above.

      Note

      Use the search bar, if needed.

    4. Select the attached permissions policy.

      Select Edit.

    5. Select the JSON tab and replace the policy with the following:

      { "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "cognito-identity:*", "kinesisvideo:*" ], "Resource": [ "*" ] } ] }

      Select Next.

    6. Select the box next to Set this new version as the default if it isn't already selected.

      Select Save changes.