Screen sharing SDK

Android tutorial

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

How to use the SDK for your app

Integrate the SDK into your app in minutes by following our Android Screen sharing SDK Tutorial.

Please read about how to use the SDK for iOS in the iOS 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 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 into 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

  • Android Version: API Level 14 (Android 4.0)

    Note: It is not necessary to set the minimum SDK version of your app to API Level 14; however, if your app is being used on devices with Android version prior to 4.0, the SDK functionality will not work.

  • Target SDK Version: We recommend API Level 19 (Android 4.4)

    <uses-sdk android:targetSdkVersion="19" />
    

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 Android 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. If 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 of the app in which 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: Aside from the settings mentioned above, it is not necessary to define further settings for the module.

Importing the SDK

For Eclipse

  1. Extract the ScreenSharingSDK-eclipse.zip file into a folder that is not already located within your app's workspace.
  2. Import the ScreenSharingSDK folder into your app's workspace.
    • Click File > Import and select Android > Existing Android Code Into Workspace.
    • Select the folder of the extracted SDK as Root Directory.
    • Make sure to activate the Copy projects into workspace checkbox.
  3. Add a dependency to the SDK.
    • Right click on your app's project and select Properties from the context menu.
    • Under Android" > Library, select Add.
    • Select the ScreenSharingSDK project.
  4. Add the required permissions and the TVSessionService to your AndroidManifest.xml. If you're using the Android SDK Tools Revision 20 or higher, you can let the Manifest Merger do the work by adding the manifestmerger.enabled property in the project.properties file of your app:

    manifestmerger.enabled=true
    

    Alternatively you need to add the following permissions to your AndroidManifest.xml manually.

    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
    <uses-permission android:name="android.permission.ACCESS_WIFI_STATE" />
    <uses-permission android:name="android.permission.INTERNET" />
    <uses-permission android:name="android.permission.SYSTEM_ALERT_WINDOW"
            android:maxSdkVersion="22" />
    <uses-permission android:name="android.permission.WAKE_LOCK" />
    

    Add the TVSessionService to the <application> tag:

    <service android:name="com.teamviewer.sdk.screensharing.api.TVSessionService" />
    

For Android Studio

  1. Extract the ScreenSharingSDK-studio.zip file into a folder of your choice.
  2. Import the Screen sharing SDK into your project by creating a new module.
    • In the File > New Module dialog, select the Import .JAR or .AAR Package option.
    • Select the ScreenSharingSDK.aar file from the zip and create a module named ScreenSharingSDK.
  3. Add the following dependency to the build.gradle file of your app (located in your app module's directory).

    dependencies {
        compile project(':ScreenSharingSDK')
    }
    

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, provide an instance of TVConfigurationID to the TVSessionConfiguration.Builder.

    final TVSessionConfiguration config = 
        new TVSessionConfiguration.Builder(
            new TVConfigurationID("YOUR_CONFIGURATION_ID"))
            .setServiceCaseName("NAME_FOR_SERVICE_CASE")
            .setServiceCaseDescription("DESCRIPTION_FOR_SERVICE_CASE")
            .build();
    

    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 TVSessionCode instance:

    final TVSessionConfiguration config = 
        new TVSessionConfiguration.Builder(new TVSessionCode("SESSION_CODE"))
            .build();
    

To start a new session call createTVSession on the TVSessionFactory and supply your SDK Token as well as an implementation of the TVSessionCreationCallback interface. A new session will be created asynchronously and will be delivered to the callback. To start the session, invoke the start() 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.

TVSessionFactory.createTVSession(this, "YOUR_SDK_TOKEN", 
    new TVSessionCreationCallback() {
        @Override
        public void onTVSessionCreationSuccess(TVSession session) {
            session.start(config);
    }

        @Override
        public void onTVSessionCreationFailed(TVCreationError error) {
        }
});

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

Note: All methods of TVSessionCreationCallback will be invoked on the main thread.

Getting notified about session events

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

session.setTVSessionCallback(new TVSessionCallback() {
    @Override
    public void onTVSessionError(TVSessionError error) {
        // React to session errors
    }

    @Override
    public void onTVSessionEnd() {
        // React to the session ending
    }
});

Note: All methods of TVSessionCallback will be invoked on the main thread.

Note: The method onTVSessionEnd() will always be called. The method onTVSessionError() 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. If 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 TVSessionCreationCallback.onTVSessionCreationSuccess() and TVSessionCallback.onTVSessionEnd().

API Reference

More detailed information on the API methods can be found in 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.

The example app relies on the Android SDK Build-tools (Rev. 20) and the SDK Platform (API 19), so please make sure you have those installed in the Android SDK Manager.

Importing the example app for Eclipse

  1. Extract the ScreenSharingSDK-android-example.zip file into a folder that is not already located within your workspace.
  2. Import the ScreenSharingSDK and the Travel projects into your workspace.
    • Click File > Import and select Android > Existing Android Code Into Workspace.
    • Select the folder with the extracted zip archive contents as Root Directory.
    • Make sure to activate the Copy projects into workspace checkbox.
  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.

Importing the example app for Android Studio

  1. Extract the ScreenSharingSDK-android-example.zip file into a folder of your choice.
  2. Import the example project.
    • Close the current project to reach the Welcome Screen.
    • Click Import Project from the Welcome to Android Studio window or from the File menu.
    • Select the folder with the extracted zip archive contents.
  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 Android from the following link: Download Example app.

Advanced

Threading concepts

In general, the Screen sharing SDK was designed with concurrency in mind. Therefore all API calls can be safely invoked from any thread. The methods of the following callbacks however are always executed on the main thread:

  • TVSessionCreationCallback
  • TVSessionCallback

ProGuard Support

When using ProGuard or DexGuard, please make sure to add the following lines to your proguard-project.txt file:

-keep class com.teamviewer.** { *; }
-dontwarn com.teamviewer.**
-dontnote com.teamviewer.**

System Alert Window

If your App uses the SYSTEM_ALERT_WINDOW permission please add the tools:remove="android:maxSdkVersion" attribute to the permission declaration:

<uses-permission android:name="android.permission.SYSTEM_ALERT_WINDOW" tools:remove="android:maxSdkVersion" />

Also make sure to add xmlns:tools="http://schemas.android.com/tools" inside the <manifest> tag.

Sending reports

If you encounter any problems during the implementation of the SDK, you can export the TeamViewer logfile. The collectLogfiles(targetZip) method will gather the SDK log files and place them on the external storage:

TVDebugTools.createInstance(getActivity()).collectLogfiles("logfiles.zip");

Note: When you want to export logfiles, you must explicitly add the WRITE_EXTERNAL_STORAGE permission to the AndroidManifest.xml of your app. Please note that this is a runtime permission since API level 23.

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.

Choose if you want to download the SDK for Eclipse or Android Studio.



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.