Appcues Capacitor Plugin
Appcues Capacitor Plugin allows you to integrate Appcues experiences into your Ionic apps for iOS and Android devices.
This capacitor is a bridge between the native Appcues SDKs in an Ionic application which sends user properties and events to the Appcues API and retrieves and renders Appcues content based on those properties and events.
🚀 Getting Started
Prerequisites
The latest package version requires Capacitor 8. Use @appcues/[email protected] for Capacitor 7.
Android
Your application's build.gradle must have a compileSdkVersion of 36+ and minSdkVersion of 24+. Your project should use the Android Gradle Plugin (AGP) version 8.13+.
android {
compileSdkVersion 36
defaultConfig {
minSdkVersion 24
}
}
Due to the SDK usage of Jetpack Compose, AGP 8 apps must apply the kotlin-android plugin in the app build.gradle. AGP 9+ enables built-in Kotlin by default and should not apply it.
plugins {
id 'com.android.application'
id 'kotlin-android' // AGP 8 only
}
iOS
Your application must target iOS 15+. Update the iOS project xcodeproj to set the deployment target, if needed.
Installation
In your app's root directory, run:
npm install @appcues/capacitor
npx cap sync
Note: You do not need to manually update your Podfile to add Appcues.
One Time Setup
Initializing the SDK
An instance of the Appcues SDK should be initialized when your app launches.
import { Appcues } from '@appcues/capacitor';
Appcues.initialize({
accountId: 'APPCUES_ACCOUNT_ID',
applicationId: 'APPCUES_APPLICATION_ID',
});
Initializing the SDK requires you to provide two values, an Appcues account ID, and an Appcues mobile 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.
Configuring Hosting Environment
By default, the Appcues SDK will send data to the United States (US) hosting environment, and no additional configuration is required. To specify a different hosting environment, pass a config with the apiBasePath and settingsHost options during initialization.
EU Hosting Environment Configuration
Appcues.initialize({
accountId: 'APPCUES_ACCOUNT_ID',
applicationId: 'APPCUES_APPLICATION_ID',
config: {
apiBasePath: 'https://api.eu.appcues.net',
settingsHost: 'https://fast.eu.appcues.com',
},
});
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.
Enabling Push Notifications
In an Ionic app, push notifications are configured in the native projects for iOS and Android. Please refer to native documentation on iOS and Android for more details. The example directory in this repository contains a reference implementation that includes push notification support.
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 a user
Appcues.identify({ userId: 'my-user-id' });
// Identify a user with property
Appcues.identify({ userId: 'my-user-id', properties: { company: 'Appcues' } });
After identifying a user, you can optionally associate that user with group.
// Associate a user with a group, optionally including group properties
Appcues.group({ groupId: 'group-id', properties: { plan: 'standard' } });
To ensure the most accurate content targeting based upon group information, it's recommended to supply the group information immediately after a new user is identified.
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 Capacitor Plugin, you can start tracking screens and events using the following methods:
// Track event
Appcues.track({ name: 'Sent Message' });
// Track event with property
Appcues.track({ name: 'Deleted Contact', properties: { id: 123 } });
// Track screen
Appcues.screen({ title: 'Contact List' });
// Track screen with property
Appcues.screen({ title: 'Contact List', properties: { reference: 'abc' } });
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.
📝 Documentation
More technical documentation about this capacitor is available in the docs. Auto-generated documentation is available here.
Full documentation is available at https://docs.appcues.com/
🎬 Examples
The example directory in this repository contains full example iOS/Android app to providing references for correct installation and 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.