Skip to content

Latest commit

 

History

History
153 lines (100 loc) · 7.5 KB

README.md

File metadata and controls

153 lines (100 loc) · 7.5 KB
Raw

Appcues Android SDK

CircleCI maven License: MIT

Appcues Android SDK allows you to integrate Appcues experiences into your native Android apps.

The SDK is a Kotlin library for sending user properties and events to the Appcues API and retrieving and rendering Appcues content based on those properties and events.

🚀 Getting Started

Prerequisites

Your application's build.gradle must have a compileSdkVersion of 34+ and minSdkVersion of 21+, and use Android Gradle Plugin (AGP) 8+.

android {
    compileSdkVersion 34

    defaultConfig {
        minSdkVersion 21
    }
}

Due to the SDK usage of Jetpack Compose, it is required to either:

  1. apply kotlin-android plugin in app's build.gradle file. 
    plugins {  
  id 'com.android.application' 
  id 'kotlin-android' 
}
  2. OR Update Android Gradle Plugin 8.4.0+

Related Google issue regarding usage of the Jetpack Compose dependency versions 1.6+

Installation

Add the Appcues Android SDK dependency to your application. There are options for a standard installation, or for usage through a Segment plugin. An installation tutorial video is also available for reference.

Standard Installation

The library is distributed through Maven Central. Add the appcues module to your build.gradle as a dependency as shown in the code sample below, and replace the <latest_version> with the latest release version listed in this repository.

repositories {
    mavenCentral()
}

dependencies {
    implementation 'com.appcues:appcues:<latest_version>'
}

Segment

Appcues supports integration with Segment's analytics-kotlin library. To install with Segment, you'll use the Segment Appcues plugin.

One Time Setup

After installing the package, you can reference Appcues Android SDK by importing the package with import com.appcues.*.

Initializing the SDK

An instance of the Appcues Android SDK should be initialized when your app launches. A lifecycle method such as the Application onCreate would be a common location:

override fun onCreate() {
    super.onCreate()
    appcues = Appcues(this, APPCUES_ACCOUNT_ID, APPCUES_APPLICATION_ID)
}

Initializing the SDK requires you to provide two values: APPCUES_ACCOUNT_ID and APPCUES_APPLICATION_ID. These values can be obtained from your Appcues settings. Refer to the help documentation on Registering your mobile app in Studio for more information.

Supporting Builder Preview and Screen Capture

During installation, follow the steps outlined in Configuring the Appcues URL Scheme. This is necessary for the complete Appcues builder experience, supporting experience preview, screen capture and debugging. Refer to the Debug Guide for details about using the Appcues debugger.

Enabling Push Notifications

During installation, follow the steps outlined in Push Notification.

Identifying Users

In order to target content to the right users at the right time, you need to identify users and send Appcues data about them. A user is identified with a unique ID.

  • identify(userId)

After identifying a user, you can optionally associate that user with group.

  • group(groupId)

Tracking Screens and Events

Events are the “actions” your users take in your application, which can be anything from clicking a certain button to viewing a specific screen. Once you’ve installed and initialized the Appcues Android SDK, you can start tracking screens and events using the following methods:

  • track(name)
  • screen(title)

Anchored Tooltips

Anchored tooltips use element targeting to point directly at specific views in your application. For more information about how to configure your application's views for element targeting, refer to the Anchored Tooltips Guide.

Embedded Experiences

Add AppcuesFrameView instances in your application layouts to support embedded experience content, with a non-modal presentation. For more information about how to configure your application layouts to use frame views, refer to the guide on Configuring an AppcuesFrameView.

Custom Components

Implement AppcuesCustomComponentView instances and register them with Appcues to take advantage of building your own components and using them in experiences. For more information refer to the guide on Configuring an AppcuesCustomComponentView

Refer to the full Getting Started Guide for more details.

📝 Documentation

SDK Documentation is available at https://appcues.github.io/appcues-android-sdk and full Appcues documentation is available at https://docs.appcues.com/

🎬 Samples

The samples directory in repository contains a full example Kotlin Android app providing references for usage of the Appcues API.

👷 Contributing

See the contributing guide to learn how to get set up for development and how to contribute to the project.

📄 License

This project is licensed under the MIT License. See LICENSE for more information.