Please note The app SDK will be deprecated with the release of 23.0 in January 2023.
Use the Register API instead
The Agillic SDK enables you to utilize the Agillic platform from within your Android App. The SDK currently includes the following functionality:
- Register devices used by a recipient in your mobile application.
- Register a recipient push notification token which enables your Agillic Solution to send push notifications to the recipient device.
- Track recipient events. Tracking can be paused and resumed when requested by the user. Tracked events can be used to define Target Groups in the Agillic Dashboard which can be used to direct targeted marketing and other communication.
- Track if an Agillic push notification has been opened
Other useful information:
- Read more about the Agillic Platform on the official Agillic website.
- And in our developer portal.
- Agillic Help Center
- The Agillic SDK for iOS can be found here: Agillic iOS SDK
- Requires minimum Android 5.0+ (API level 21+)
Learn how to Add SDK as a dependency using Gradle
dependencyResolutionManagement {
repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
repositories {
google()
mavenCentral()
jcenter()
//Add this line
maven { url "https://jitpack.io" }
}
}
dependencies {
implementation 'com.github.agillic:agillic-android-sdk:0.8'
}
NOTE: This is not the recommended method.
In order to use the SDK you have to initialize and configure it first.
You can configure your Agillic instance in code using the following credentials:
AGILLIC API KEY
AGILLIC API SECRET
AGILLIC SOLUTION ID
See how to setup your Agillic Solution and obtain these values in the Agillic Solution Setup Guide.
Start by importing the Agillic Module into your app component
import Agillic
Initialize and configure the Agillic SDK upon launch
class MyApplication : Application() {
override fun onCreate() {
super.onCreate()
Agillic.configure(apiKey = "AGILLIC API KEY", apiSecret = "AGILLIC API SECRET", solutionId = "AGILLIC SOLUTION ID")
}
}
The Agillic instance is now ready to use.
Prerequisites
- You need to make sure to do this after
Agillic.configure()
. - You must do this upon every launch before doing any App View Tracking.
- Register has to be done in your Sign Up/Sign In flow but also on you splash screen if users are automatically logged in with an Access Token.
RECIPIENT ID
- Has to match the selected ID of the Reicipeint in Agillic. Read how to change the RecipientID
Agillic.register(recipientId = "RECIPIENT ID", activity = <Activity>)
Prerequisites
- Setup the Firebase Cloud Messaging SDK
- Read the AgillicPushNotificationSetup document to learn how to send push notifications to your Android application directly from your Agillic Solution. NOTE: This requires you to have already obtained the Recipient ID and that you store this across app sessions - this is currently only supported for unknown recipients.
FirebaseMessaging.getInstance().token.addOnCompleteListener(OnCompleteListener { task ->
if (!task.isSuccessful) {
return@OnCompleteListener
}
val token: String = task.result ?: return
Agillic.register(recipientId = "RECIPIENT ID", pushNotificationToken = token, activity = <Activity>)
})
class FirebaseMessagingServiceImpl : FirebaseMessagingService() {
override fun onNewToken(token: String) {
super.onNewToken(token)
Agillic.register(recipientId = "RECIPIENT ID", pushNotificationToken = token, activity = <Activity>)
}
}
If you wish to remove a push token from an Agillic Recipient, you can use the unregister
function. This should be done when a user is logging out of your app.
Agillic.unregister(recipientId = "RECIPIENT ID", pushNotificationToken = pushToken, context = context)
The SDK can be used to track if a user has opened a Push Notification sent from Agillic. To do this, pass the push notification data payload, received when a push notification is clicked, to the handlePushNotificationOpened
SDK function.
When a push notification is clicked, while the application is running, and your launcher activity is set to launchMode singleTop, the data payload will be sent to your launcher activity's onNewIntent function.
override fun onNewIntent(intent: Intent?) {
super.onNewIntent(intent)
// Retrieve data payload
val extras = intent?.extras
// Retrieve each payload value (optional)
val title = extras.get("title")
val body = extras.get("body")
val image = extras.get("image")
val agillicPushId = extras.get("agillic_push_id")
val onClick = extras.get("on_click")
// Track push opened
if (extras != null) {
Agillic.handlePushNotificationOpened(extras)
}
}
If your launcher activity has another launchMode or if the application is not running, the data payload will be sent to your launcher activity's onCreate function.
override fun onCreate(savedInstanceState: Bundle?) {
super.onCreate(savedInstanceState)
// Retrieve data payload
val extras = intent?.extras
// Retrieve each payload value (optional)
val title = extras.get("title")
val body = extras.get("body")
val image = extras.get("image")
val agillicPushId = extras.get("agillic_push_id")
val onClick = extras.get("on_click")
// Track push opened
if (extras != null) {
Agillic.handlePushNotificationOpened(extras)
}
}
Agillic push notifications always contain a data payload. Thus the notification will always be delivered to your onMessageReceived callback in your FirebaseMessagingService implementation. If the application receives a push notification while running in the foreground, you will need to generate your own notification in order to display it. See the sendNotification method in the following example.
override fun onMessageReceived(remoteMessage: RemoteMessage) {
super.onMessageReceived(remoteMessage)
val data = remoteMessage.data
val title = data["title"]
val body = data["body"]
val image = data["image"]
val agillicPushId = data["agillic_push_id"]
val onClick = data["on_click"]
}
Track recipient behavior with App View Tracking
App View Tracking is typically done in your Activity
or Fragment
file, but can be used elsewhere if needed.
override fun onResume() {
super.onResume()
val appView = AgillicAppView(screenName = "app://sublevel-1/sublevel-2")
Agillic.track(appView)
}
The screenName
is the value that can be matched in the Condition Editor.
We suggest to use a hierarchical naming convention, prefixed with app://
ex:
app://sublevel-1/sublevel-2/...
Examples of usage:
app://landingpage
app://landingpage/sign-up/step-2
app://dashboard
app://product-offers
app://product-offers/21
app://menu/profile/edit
NOTE: Work in progress
Most SDK functions accept an optional callback parameter which can be added in order to gain information on what's happening in the SDK and when. See the following example:
Agillic.register(
recipientId = "<RECIPIENT_ID>",
pushNotificationToken = "<PUSH_NOTIFICATION_TOKEN>",
activity = this,
registerCallback = object : Callback {
override fun info(response: String) {}
override fun failed(response: String) {}
override fun success(response: String) {}
}
)
Please provide any feedback via a GitHub Issue.
Agillic SDK for Android is available under the Apache 2.0 license. See LICENSE file for more info.
Copyright 2022 Agillic
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.