From f7f1ee8fd64aa4f766d2f11b7d99ce7427581a62 Mon Sep 17 00:00:00 2001 From: diftodi Date: Tue, 18 Oct 2022 16:55:40 +0300 Subject: [PATCH 1/2] Android readme.md updated --- README.md | 267 ++++++++++++++++++++++++++++++++++++------------------ 1 file changed, 181 insertions(+), 86 deletions(-) diff --git a/README.md b/README.md index f630010..a71f036 100644 --- a/README.md +++ b/README.md @@ -1,140 +1,235 @@ -[![Android SDK tests](https://github.com/extole/android/actions/workflows/sdk-test.yml/badge.svg?branch=master&event=schedule)](https://github.com/extole/android/actions/workflows/sdk-test.yml) +# Android Integration +This integration guide shows you how to set up and launch an Extole program as quickly as possible with our Android SDK. -# Extole Android SDK +## Requirements +The Extole Android SDK supports minSdkVersion 21 or later. -This app provides source code examples of how to: -- send an event to Extole -- get a resource (text, url, data) describing a marketing campaign configured in Extole -- share via email through Extole -- share using Android native share +## Add Extole’s Github repository and SDK library +In the `settings.gradle` of your Android project, add Extole’s Github repository: -Screenshot: +``` +maven { + name "Extole SDK Repository" + url "https://maven.pkg.github.com/extole/android" + credentials { + username = System.getenv('GITHUB_USER') + password = System.getenv('GITHUB_PERSONAL_ACCESS_TOKEN') + } +} +``` -[](https://github.com/extole/android-sdk/blob/master/app/src/main/java/com/extole/androidsdk/MainActivity.kt) +_Github currently requires that you input your credentials to view public assets._ +In the `build.gradle` for your project add Extole’s SDK library: -## Setup +``` +implementation 'com.extole.mobile:android-sdk:1.0.+' +``` -1. Clone this repository -2. Open it with Android Studio -3. Run it in a simulator or real device -4. Declare ENV variables `GITHUB_USER` and `GITHUB_PERSONAL_ACCESS_TOKEN` for more details refer to: https://docs.github.com/en/packages/working-with-a-github-packages-registry/working-with-the-gradle-registry +## Initialize Extole -Note: dependencies for this project are not published to a public repository at this moment. +Initialize Extole. We recommend that you have a single instance of the Extole class: -## Using the Extole SDK +``` +Extole.init(context = context, appName = "your-app-name") -### Repository +``` -To your project `build.gradle` under the `repositories` configuration, add: +A test sandbox can also be used in the example above (i.e., sandbox = “production-test”). Be sure to replace `appName = "your-app-name"` with a name that describes your application so that you can easily find it later. Optionally, it’s useful to pass a version… ` data = {"version" to "1.0"}` +Initialize global components. The following example uses the dependency injection framework [Dagger](https://dagger.dev/dev-guide/android.html): ``` -maven { - name "github" - url "https://maven.pkg.github.com/extole/android-sdk" +@Module +@InstallIn(SingletonComponent::class) +class Configuration { + @Singleton + @Provides + fun extole(@ApplicationContext context: Context): Extole = + runBlocking(Dispatchers.IO) { + return@runBlocking Extole.init( + context = context, appName = "extole-mobile-test", data = mapOf("version" to "1.0"), + sandbox = "prod-test", labels = setOf("business"), + listenToEvents = true + ) + } } ``` -### Dependencies - -On your application `build.gradle` file Add a dependency on `Extole Android SDK`: - +In the `AndroidManifest.xml` file, under the tag `<application></application>` add: ``` -implementation 'com.extole.mobile:android-sdk:1.0.0' + ``` +You need to use your program domain in order for the application to communicate with Extole. -### Project configuration +## Exchange data with Extole +You can easily set up the SDK to send Extole information about your customers or members and the events they generate. as well as to receive content from Extole. -Modify `AndroidManifest.xml`, add: +### Customer Data +Send Extole information about the customer: ``` - - - +extole.identify(email, {"member_id" to "123"}) ``` +You can choose to pass any type of data to describe the customer. Richer data about your customers gives your marketing team the information they need to better segment your program participants and target them with appropriate campaigns. -### Initializing SDK -We recommend that you keep a reference to the `extole` and share it between activities. +### Event Data +Send Extole events, such as registers, signups, conversions, account openings, etc: +``` +extole.sendEvent("my_event", {"key" to "values"}) +``` +For each event type, you can send additional data. For example, on a conversion event you may want to pass in order ID or order value and so on. +### CTA Content +CTAs such as mobile menu items can be fully customized in the My Extole Campaign Editor. Each CTA has a designated zone. The following code is an example of how to retrieve a CTA by fetching zone content: ``` -val extole = Extole.builder() - .withPersistance(SharedPreferencesPersistance(context)) - .withAppName("YOUR-APPLICATION-NAME") - .addData("version", "YOUR-APPLICATION-VERSION") - .build() +val (zone, campaign) = extole.fetchZone("cta_prefetch") +runOnUiThread { + findViewById(R.id.cta_text) + .setText(zone?.get("text").toString(),TextView.BufferType.NORMAL) + findViewById(R.id.cta_image) + .setText(zone?.get("image").toString(),TextView.BufferType.NORMAL) + zone.sendEvent("cta_clicked") +} + ``` -### Rendering content for a menu item example +## In order to be able to fetch the `cta` zone, the zone should be configured in My Extole and should return JSON content containing the `image` and `text`. +Important note: We encourage you to pull CTA content from My Extole because doing so ensures that your menu item or overlay message will reflect the copy and offer you’ve configured for your campaign. + +## Advanced Usage +The following topics cover advanced use cases for the Extole Android SDK. If you would like to explore any of these options, please reach out to our Support Team at support@extole.com. -Allowing the marketer to manage the call to action messaging to align with the marketing campaign. +### Deeplink integration +Completing a deep link integration is simple once you have integrated with a deep link provider, such as Branch. Send a mobile event to Extole, and based on the configuration of your mobile operations, our framework will execute the corresponding action. +Deep link example: ``` -GlobalScope.launch { - val (zone, campaign) = extole.getZone("promotional_menu") - runOnUiThread { - findViewById(R.id.promotional_menu_item).setText( - zone.get("menu_text").toString(), TextView.BufferType.NORMAL - ) - } +DeepLinkListener { linkProperties, error -> + GlobalScope.launch { + ServiceLocator.getExtole(this@DeeplinkActivity) + extole.sendEvent("deeplink", linkProperties) + } } ``` +Extole will be able to react to this based on the Campaign configuration in[ ](http://my.extole.com/)My Extole. -This example assumes you have configured the 'promotional_menu' zone with 'menu_text' in Extole. - -### WebView example - -A webview is a convenient way to support a rich campaign experience, while minimizing mobile development. Extole, -supports tracking important events in the webview, like tracking native sharing events. +### Configuring Actions from Events +You can set up a specific action to occur when an event is fired. For example, when a customer taps on your menu item CTA, you may want the event to trigger an action that loads your microsite and shows the share experience. +To set up this type of configuration, you will need to work with Extole Support to set up a zone in My Extole that returns JSON configurations with conditions and actions. The SDK executes actions for conditions that are passing for a specific event: ``` -GlobalScope.launch { - val (zone, campaign) = extole.getZone("promotional_menu") - runOnUiThread { - val menuItemButton = findViewById