Amazon Kinesis Video Streams 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 SDK
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 SDK
Complete the following steps:
-
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). -
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:
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
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.mBuild
again.
-
Configure Amazon Cognito (user pool and identity pool) settings. For details steps, see Configure Amazon Cognito for the SDK. This generates authentication and authorization settings required to build the iOS WebRTC SDK.
-
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 SDK. -
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 SDK. -
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 sample application
Complete the following steps:
-
On your iOS device, open AWSKinesisVideoWebRTCDemoApp and log in using either a new (by creating it first) or an existing Amazon Cognito account.
-
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.
-
(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.
-
Choose the AWS Region and whether you want to send audio or video data, or both.
-
To verify peer-to-peer streaming, do any of the following:
Note
Ensure that you specify the same signaling channel name, AWS region, viewer ID, and the AWS 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 Amazon Kinesis Video Streams with 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 Amazon Kinesis Video Streams with 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 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
-
Sign in to the Amazon Cognito console
and verify the region is correct. -
In the navigation on the left choose User pools.
-
In the User pools section, choose Create user pool.
-
Complete the following sections:
Step 1: Configure sign-in experience - In the Cognito user pool sign-in options section, select the appropriate options.
Select Next.
Step 2: Configure security requirements - Select the appropriate options.
Select Next.
Step 3: Configure sign-up experience - Select the appropriate options.
Select Next.
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.
Step 5: Integrate your app - Select the appropriate options.
In the Initial app client field, choose Confidential client.
Select Next.
Step 6: Review and create - Review your selections from the previous sections, then choose Create user pool.
-
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 isCognitoUserPool.Default.PoolId
. -
Select the App integration tab and go to the bottom of the page.
-
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 isCognitoUserPool.Default.AppClientId
. -
Show the Client secret and make note of this for later. In the
awsconfiguration.json
file, this isCognitoUserPool.Default.AppClientSecret
.
Set up an identity pool
To set up an identity pool
-
Sign in to the Amazon Cognito console
and verify the region is correct. -
In the navigation on the left choose Identity pools.
-
Choose Create identity pool.
Configure the identity pool.
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.
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.
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.
Step 4: Configure properties - Type a name in the Identity pool name field.
Select Next.
Step 5: Review and create - Review your selections in each of the sections, then select Create identity pool.
-
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 isCredentialsProvider.CognitoIdentity.Default.PoolId
. -
Update the permissions for the IAM role.
Sign in to the AWS Management Console and open the IAM console at https://console.aws.amazon.com/iam/
. In the navigation on the left, choose Roles.
Find and select the role you created above.
Note
Use the search bar, if needed.
Select the attached permissions policy.
Select Edit.
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.
Select the box next to Set this new version as the default if it isn't already selected.
Select Save changes.