Developer's Guide to Installing the Pendo Android SDK

Important: This article includes code examples that do not include the api key and scheme IDs required to successfully install the SDK. A Pendo admin in your subscription can access these unique IDs in App Details under Subscription Settings or in Install Settings in App Details.

Overview

Pendo captures product usage data, user feedback, and lets you communicate in-app to onboard, educate, and guide users to value. Pendo tagging and guides are codeless, no engineering resources are required. However, we need engineers to install the SDK and initialize Pendo in your app. Information about Pendo and the general installation process is available in the Installation Planning article. With preparation, the technical installation of the Pendo SDK is straightforward.

The SDK is the only technical piece of the initial Pendo installation. Once the SDK is properly installed anyone can use Pendo. The SDK tracks a visitor’s activity in your app, loads guides, and captures session metadata. Additional development may be done later to optimize and expand the use of Pendo for mobile, like track events. The SDK in your mobile app also needs to be updated when we release new versions to use the latest Pendo features.

Pendo has integrations with other popular CRM, analytics, and collaboration tools. The scope of integrations ranges from native integrations with a codeless installation wizard to custom development and will not be covered in this article. Check our Integrations articles for help with our popular integrations or reach out to a Pendo representative for help with integrations in your subscription after completing the SDK install.

 

Requirements

  • Mobile SDK 2.10 or greater
  • compileSdkVersion 30
  • AndroidX minSdkVersion 21 or greater
  • Android Support minSdkVersion 21 or greater
  • JavaVersion.VERSION_1_8
  • Enable AndroidX if your project does not use an older version of the Support Library (gradle.properties)
  • App Permissions requirements (AndroidManifest)
    <uses-permission android:name="android.permission.INTERNET" />
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>

 

Install the SDK

Add the SDK repositories and dependencies in your app. Verify that your app meets all version requirements. When this is complete, you need to setup and initialize Pendo to identify the user, collect data, and load guides.

1. Add Pendo repository to build.gradle.

repositories {
  maven {
  url "https://software.mobile.pendo.io/artifactory/androidx-release"
// <For Android Support (not AndroidX) use the following instead>  url "https://software.mobile.pendo.io/artifactory/android-release"
  }
  mavenCentral()
}

 

2. Add Pendo dependency to build.gradle.

dependencies {
   implementation group:'sdk.pendo.io' , name:'pendoIO', version:'2.17.+', changing:true
}

 

Pendo Setup and Initialization

The SDK initialization has two parts, importing the SDK and initializing the SDK when the visitor is identified. The Pendo SDK is imported during application onCreate. The initialization call can occur in any activity where you want to identify the current visitor and the start a session.

Pendo must be initialized to identify the user, begin data collection, and display guide content. The SDK can be initialized when the visitor is authenticated and metadata is known or with an anonymous visitor. Initialization can occur when the application starts, later when the visitor is identified, or any time you need to identify the current visitor and start a new session.

Identified visitors use a defined schema to create visitor and account objects with associated metadata in Pendo. Refer to the article on Visitor and Account Metadata for additional information on how this data is defined and used in Pendo. Passing null or "" as the visitorId will generate an anonymous visitor ID.

  • visitorId - String containing a unique User ID (e.g. "user-SFGH-56gh"), this ID should match the visitor ID for any other Pendo web or mobile apps
  • accountId - String containing unique Account ID, affiliation of the visitor to a specific company or group (e.g. Acme Inc), this ID should match the visitor ID for any other Pendo web or mobile apps
  • visitorData - Visitor metadata (e.g email, phone, country, etc.) 
  • accountData - Account metadata (e.g tier, level, ARR, etc)

 

1. Setup Pendo in Application class

Add the following code in the onCreate method in the application class.

setup is settings up the SDK and initializing it.

import sdk.pendo.io.*;

String pendoAppKey = "<REPLACE_THIS_WITH_YOUR_API_KEY>";

Pendo.setup(
  this,
  pendoAppKey,
  PendoPhasesCallbackInterface);

 

2. Initialize Pendo in the activity/fragment where your visitor is identified

Pendo.startSession starts a new session, begins data collection, and loads guides with the provided metadata. This can identify an authenticated user or generate a random visitor ID for an anonymous visitor. Calling pendo.startSession again ends the current session and starts a new session, begins data collection, and loads guides using the new visitor metadata that is passed through.

Add the following code to initialize Pendo and identify the current visitor.

Pendo.startSession (
visitorId,
accountId,
visitorData,
accountData);

Note: pendo.startSession can be used at any time to update the current visitor, must be called after SDK is initialized.

 

Setup Device Connection

To allow tagging your application with Pendo and testing guides, Add the activity with your scheme ID in AndroidManifest.xml.

1. Open the application AndroidManifest.xml file.

2. Add the following <activity> to the manifest in the <application> tag.

<activity android:name="sdk.pendo.io.activities.PendoGateActivity" android:launchMode="singleInstance">
 <intent-filter>
   <action android:name="android.intent.action.VIEW"/>
   <category android:name="android.intent.category.DEFAULT"/>
   <category android:name="android.intent.category.BROWSABLE"/>
   <data android:scheme="<REPLACE_WITH_YOUR_SCHEME_ID>"/>
 </intent-filter>
</activity>
  • Your scheme ID and app key are in App Details in Subscription Settings

Using Proguard

If you’re using proguard-android-optimize.txt, add the following in the optimizations code line.

!code/allocation/variable

Your optimizations line should look like this.

-optimizations *other optimizations*,!code/allocation/variable

 

Verify Installation

1. Using Android Studio, run the app and search in the device log for

PendoInternal: Pendo Mobile SDK was successfully integrated and connected to the server. App version identified: '<version>'.

 

2. Confirm that you can see your app under subscription settings as Integrated.

AndroidIntegrated.png

 

Android Services Support

If your application leverages Android Services, please refer to our Support Applications Running Android Services article to ensure consistent behavior and data. This solution is supported for Pendo Android SDK 2.3.9 and 2.4.3+.

 

Additional Configuration

Pendo Android API Documentation contains additional technical information for configuring the Pendo SDK in the your application.

 

Troubleshooting

Review the latest Pendo Mobile SDK release notes for any compatibility issues.

If you are encountering Dex problems, please refer to https://developer.android.com/studio/build/multidex.

Common Issues

Build Issue (Gradle): Pendo Mobile SDK uses a different version of the gson library than your App

There are two possible solutions.

1. Upgrade the local gson dependency you use through the Gson repository.

2. Exclude the gson library from Pendo dependency by adding the following statement under the dependencies section in the build gradle.

compile('<pendo aar>') {

transitive = true;

exclude module: 'gson'

}

 

Build Issue (Gradle): Dex index overflow exception -> multi dex

Your app has reached the Android system method amount limit. You can configure multi dex to address this issue, refer to the Android Developer enable multidex article.

 

Build Issue (Gradle): Conversion to Dalvik format failed: Unable to execute dex: method ID not in [0, 0xffff]: 65536

Your app has reached the Android system method amount limit. you can configure multi dex to address this issue, refer to the Android Developer enable multidex article.

 

Build Issue (Gradle): Trouble writing output: Too many field references: 131000; max is 65536. You may try using –multi-dex option.

Your app has reached the Android system method amount limit. you can configure multi dex to address this issue, refer to the Android Developer enable multidex article.

 

Build Issue (Gradle): Dex out of memory

You need to limit the dex memory usage. A helpful solution is available on stackoverflow.

 

Build Issue (Gradle): Manifest merger failed : uses-sdk:minSdkVersion 9 cannot be smaller than version 14 declared in library …../app/build/intermediates/exploded-aar/sdk.insert.io/insertIO/0.1-SNAPSHOT/AndroidManifest.xml

Pendo Mobile SDK will only work with API level 14 and onwards. To work with Pendo Mobile, you must change minSdkVersion to 14. It is possible to upload two variants of your Android App into Google Play. One for older versions without Pendo and one for newer versions which includes the Pendo Mobile SDK.

 

Runtime issue: Logcat errors indicate that the Pendo SDK does not connect to the Pendo server 

Make sure that your organization has enabled access to Pendo Mobile URLs.