Screen sharing SDK

iOS tutorial

Learn how to integrate the TeamViewer Screen sharing SDK into your iOS app.

How to use the SDK for your app

Integrate the SDK into your iPhone and iPad apps. Achieve quick results by following our iOS Screen sharing SDK Tutorial.

Please read about how to use the SDK for Android in the Android tutorial.


General

Definitions

  • Service case: A service case represents a user's request for in-app support and is listed in the service queue.

  • Session code: A unique identifier that is used to connect to a service case.

  • Session: The app user has connected to a session code and is either being supported or currently waiting for support.

  • Service queue: The service queue is a TeamViewer feature that could be compared to a ticket system. A user who needs help submits a ticket (service case), all tickets are managed within the ticket system (service queue).

Handling support requests

The SDK provides two different methods for handling user requests.

  • Automatically generate a service case (recommended): A service case is automatically created and added to the service queue of the support technician once the user requests for help. For this, a so called Configuration ID is required. The user just needs to click on a help button within your app. When the request is submitted, a service case appears in a predefined group within the service queue of the support technician. The supporter can then connect to the app via TeamViewer.

  • Connecting to an existing service case: Users have to manually enter a provided TeamViewer session code (e.g. s12-345-678). For this, the support technician needs to create a session code and then share this code with the user asking for help. If the user enters the session code within your app, the support technician can then establish a session.

For further information on service cases, please see the TeamViewer Manual - Management Console, chapter 4.

Requirements

  • Xcode Version: 7.0 or later (iOS SDK Version 9.0 or later)

  • iOS Version: iOS 7, iOS 8 and iOS 9

  • Architecture: armv7, arm64 (32-bit / 64-bit)
  • BitCode is not supported yet

    Note: The SDK might also work on iOS 6 devices. However, iOS 6 is not officially supported.

Before you start

Before integrating the SDK into your app, make sure to complete the following tasks:

Download the SDK

Download the SDK from the top of this website or the following link: Download iOS SDK.

Create a SDK Token

The SDK uses a token to authenticate itself to the TeamViewer network. This token is managed within the TeamViewer Management Console. To create a token, follow these steps:

  1. Click on the following Link: Create token and log in with your TeamViewer account. In case you don't have a TeamViewer account yet, click on Sign Up.

  2. Enter the App Name in which you will include the SDK. You can leave a Description to further specify your app.

  3. Choose the Operating System off the app you want to include the SDK.

    The Create app dialog within the TeamViewer Management Console to create a SDK Token

    Note: If you want to include the SDK into an iOS AND Android app, please use two different tokens!

  4. Click Save.

  5. Your unique SDK Token is displayed.

    Create Token

Create a Configuration ID (recommended)

If you chose to automatically create a new service case when the user requests support, you have to create a Configuration ID as follows:

  1. Create a new custom QuickSupport module within the TeamViewer Management Console under https://login.teamviewer.com/nav/menu/designanddeploy.

  2. Enter a Name for the module.

  3. Activate the Automatically add users to a group in your Contacts list option.

    create configuration id for screen sharing sdk for ios android

  4. Choose a group from the Group list.

  5. Click Save.

  6. Click on the name of the recently created Module.

  7. The Configuration ID can be found in the bottom right corner of the dialog window.

    You can find the Configuration ID in the QuickSupport settings

Use the Configuration ID during the coding process as described below.

Note: Beside the settings mentioned above, it is not necessary to define further settings for the module.

Importing the SDK

  1. Extract the ScreenSharingSDK-iOS.zip file into a folder of your choice.

  2. Drag&Drop the ScreenSharingSDK.framework into your app's project.

  3. Add the required frameworks to your app's project :

    Select your project under Project > Build Phases > Link Binary With Libraries > press '+' and add the following frameworks and libraries:

    • AudioToolbox.framework

    • SystemConfiguration.framework

    • UIKit.framework

    • libz.dylib

  4. Set linker flags:

    Select your project under Project > Build Settings > Linking and add the following linker flags:

    • Add '-lc++' (C++ Standard library) to the 'Other linker flags' in your project 'Build Settings'.

    • Add '-ObjC' to the 'Other linker flags' to link Categories from the ScreenSharingSDK.framework in your app.

  5. Set the architecture (ARCHS) in your project Build Settings Project > Build Settings > Architectures > Architectures to 'armv7' or 'arm64'.

    Note: The Screen sharing SDK is built for armv7 and arm64 architectures.

  6. Drag&Drop the ScreenSharingSDKResource.bundle into your project.

The ScreenSharingSDKResource.bundle is required, since it provides all resources.

Note: It's important to place the ScreenSharingSDKResource.bundle in the main bundle of your app.

Start coding

Creating and starting sessions

For starting a session, you need to supply a valid TVSessionConfiguration. This configuration specifies the method for handling service cases.

As mentioned before, you can either use a configuration ID and create a new service case, or connect to an already existing service case via its session code.

  • Using a configuration ID: If you want to create a new service case on session startup, create a TVSessionConfifuration with your Configuration ID.
    Objective-C:

    TVSessionConfiguration *sessionConfiguration = [TVSessionConfiguration tvSessionConfigurationWithBlock:^(TVSessionConfigurationBuilder *builder) 
    {
        builder.configurationId = @"CONFIGURATION_ID";
        builder.serviceCaseName = @"NAME_FOR_SERVICE_CASE";
        builder.serviceCaseDescription = @"DESCRIPTION_FOR_SERVICE_CASE";
    }];
    

    Swift:

    let sessionConfiguration : TVSessionConfiguration = TVSessionConfiguration.tvSessionConfigurationWithBlock({
        (builder: TVSessionConfigurationBuilder!) -> Void in
        builder.configurationId = "CONFIGURATION_ID"
        builder.serviceCaseName = "NAME_FOR_SERVICE_CASE"
        builder.serviceCaseDescription = "DESCRIPTION_FOR_SERVICE_CASE"
    })
    

As seen in this example you can directly set a name and description for the service case. You can utilize this feature to give your users the possibility to enter their names and provide an initial description of the problem.

  • Using a session code:

    If you want to use the session code of an already existing service case, create a TVSessionConfiguration using a Session Code:
    Objective-C:

    TVSessionConfiguration *sessionConfiguration = [TVSessionConfiguration tvSessionConfigurationWithBlock:^(TVSessionConfigurationBuilder *builder) 
    {
        builder.sessionCode = @"SESSION_CODE";
    }];
    

    Swift:

    let sessionConfiguration : TVSessionConfiguration = TVSessionConfiguration.tvSessionConfigurationWithBlock(
    {
        (builder: TVSessionConfigurationBuilder!) -> Void in
        builder.sessionCode = "SESSION_CODE"
    })
    

To start a new session call createTVSessionWithToken:delegate: on the TVSessionFactory and supply your SDK Token as well as an implementation of the TVSessionCreationDelegate protcol.

A new session will be created asynchronously and will be delivered to the delegate. To start the session, invoke the startWithConfiguration: method with your previously created TVSessionConfiguration.

A connection to the TeamViewer network will be established and the supporter will be able to connect to the app shortly afterward.

Objective-C:

NSString *sdkToken = @"YOUR_SDK_TOKEN"
[TVSessionFactory createTVSessionWithToken:sdkToken delegate:self];

- (void)sessionCreationSuccess:(TVSession *)session 
{
    [session startWithConfiguration:sessionConfiguration];
}

- (void)sessionCreationFailed:(NSError *)error {
    // Handle creation errors
}

Swift:

let sdkToken : String = "<YOUR SDK TOKEN>"
TVSessionFactory.createTVSessionWithToken(sdkToken, delegate: self)

func sessionCreationSuccess(session: TVSession!) {
    session.startWithConfiguration(sessionConfiguration)
}

func sessionCreationFailed(error: NSError!) {
    // Handle creation errors
}

Note: Keep your SDK token private and don't commit it to your repository!

Getting notified about session events

In case you want to react to events that can happen during a session, for example to update your UI, you can register your own TVSessionDelegate implementation.

Objective-C

- (void)sessionCreationSuccess:(TVSession *)session {
    [session setSessionDelegate:self];
}

- (void)sessionDidFailWithError:(NSError *)error {
    // React to session errors
}

- (void)sessionDidEnd {
    // React to the session ending
}

Swift:

func sessionCreationSuccess(session: TVSession!) {
    session.setSessionDelegate(self)
}

func session(DidFailWithError error: NSError!) {
    // React to session errors
}

func sessionDidEnd() {
    // React to the session ending
}

Note: The method sessionDidEnd will always be called. The method sessionDidFail will only be called in event of an error, but it is ensured that you will receive this before the session ends.

Stopping a session

Usually a session is stopped by the user by dragging the session icon onto the

close icon. In case you want to programmatically stop the session, you can call the

stop method on the TVSession object.

Checking for a running session

In some cases, you might want to adapt your UI based on whether a session is running or

not, for example to enable or disable buttons or input fields.

The session exists between TVSessionFactory createTVSessionWithToke:delegate: and

TVSessionDelegate sessionDidEnd.

API Reference

More detailed information on the API methods can be found within the Reference documentation.

Example app

We provide a simple example app to illustrate the implementation and functionality of the SDK. See how easy it is to integrate the SDK into any of your own apps.

Importing the example app for Xcode

  1. Extract the ScreenSharingSDK-iOS-example.zip file into a folder of your choice.

  2. Open the TravelApp project file by double clicking.

  3. Fix the two build breaks within our example app. These are the positions where you need to insert your own SDK Token and Configuration ID. When you have inserted this information, it will be possible to compile and run the example app.

    • Afterward, every time you request a remote control session on the device, the request appears within your service queue.

    • Connect to the app from any TeamViewer full version.

Download the Example app for iOS from the following link: Download Example app.

Advanced

Threading concepts

In general the Screen sharing SDK was designed with concurrency mind. Therefore all API calls can be safely invoked from any thread.

Sending reports

In case you are facing any problems during the implementation of the SDK, you can extract the TeamViewer logfile by opening the Organizer in Xcode > got to your application on the according device > click /Library/Logs/TeamViewer/TeamViewer9_Logfile.log.

App Store

Please get in touch with us in case you want to upload your app onto the Apple App Store.

Download

By clicking "I accept" below, you confirm that you have read and understood the TeamViewer App Developer Agreement and agree to be bound by them.