Skip to content

Commit f7f1ee8

Browse files
daniftodidaniftodi
committed
Android readme.md updated
1 parent 22a8d90 commit f7f1ee8

File tree

1 file changed

+181
-86
lines changed

1 file changed

+181
-86
lines changed

‎README.md‎

Lines changed: 181 additions & 86 deletions
Original file line numberDiff line numberDiff line change
@@ -1,140 +1,235 @@
1-
[![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)
1+
# Android Integration
2+
This integration guide shows you how to set up and launch an Extole program as quickly as possible with our Android SDK.
23

3-
# Extole Android SDK
4+
## Requirements
5+
The Extole Android SDK supports minSdkVersion 21 or later.
46

5-
This app provides source code examples of how to:
6-
- send an event to Extole
7-
- get a resource (text, url, data) describing a marketing campaign configured in Extole
8-
- share via email through Extole
9-
- share using Android native share
7+
## Add Extole’s Github repository and SDK library
8+
In the `settings.gradle` of your Android project, add Extole’s Github repository:
109

11-
Screenshot:
10+
```
11+
maven {
12+
name "Extole SDK Repository"
13+
url "https://maven.pkg.github.com/extole/android"
14+
credentials {
15+
username = System.getenv('GITHUB_USER')
16+
password = System.getenv('GITHUB_PERSONAL_ACCESS_TOKEN')
17+
}
18+
}
19+
```
1220

13-
[<img src="https://user-images.githubusercontent.com/304224/130804856-ee7b5404-4a8d-4975-ad17-85cc0bf6e253.png" width="150">](https://github.com/extole/android-sdk/blob/master/app/src/main/java/com/extole/androidsdk/MainActivity.kt)
21+
_Github currently requires that you input your credentials to view public assets._
22+
In the `build.gradle` for your project add Extole’s SDK library:
1423

15-
## Setup
24+
```
25+
implementation 'com.extole.mobile:android-sdk:1.0.+'
26+
```
1627

17-
1. Clone this repository
18-
2. Open it with Android Studio
19-
3. Run it in a simulator or real device
20-
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
28+
## Initialize Extole
2129

22-
Note: dependencies for this project are not published to a public repository at this moment.
30+
Initialize Extole. We recommend that you have a single instance of the Extole class:
2331

24-
## Using the Extole SDK
32+
```
33+
Extole.init(context = context, appName = "your-app-name")
2534
26-
### Repository
35+
```
2736

28-
To your project `build.gradle` under the `repositories` configuration, add:
37+
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"}`
38+
Initialize global components. The following example uses the dependency injection framework [Dagger](https://dagger.dev/dev-guide/android.html):
2939

3040
```
31-
maven {
32-
name "github"
33-
url "https://maven.pkg.github.com/extole/android-sdk"
41+
@Module
42+
@InstallIn(SingletonComponent::class)
43+
class Configuration {
44+
@Singleton
45+
@Provides
46+
fun extole(@ApplicationContext context: Context): Extole =
47+
runBlocking(Dispatchers.IO) {
48+
return@runBlocking Extole.init(
49+
context = context, appName = "extole-mobile-test", data = mapOf("version" to "1.0"),
50+
sandbox = "prod-test", labels = setOf("business"),
51+
listenToEvents = true
52+
)
53+
}
3454
}
3555
```
3656

37-
### Dependencies
38-
39-
On your application `build.gradle` file Add a dependency on `Extole Android SDK`:
40-
57+
In the `AndroidManifest.xml` file, under the tag `&lt;application>&lt;/application>` add:
4158
```
42-
implementation 'com.extole.mobile:android-sdk:1.0.0'
59+
<meta-data
60+
android:name="com.extole.PROGRAM_DOMAIN"
61+
android:value="https://share.client.com/" />
4362
```
63+
You need to use your program domain in order for the application to communicate with Extole.
4464

45-
### Project configuration
65+
## Exchange data with Extole
66+
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.
4667

47-
Modify `AndroidManifest.xml`, add:
68+
### Customer Data
69+
Send Extole information about the customer:
4870

4971
```
50-
<meta-data
51-
android:name="com.extole.PROGRAM_DOMAIN"
52-
android:value="YOUR_PROGRAM_DOMAIN" />
53-
54-
<receiver
55-
android:name=".android.sdk.impl.ExtoleShareBroadcastReceiver"
56-
android:exported="false" />
72+
extole.identify(email, {"member_id" to "123"})
5773
```
74+
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.
5875

59-
### Initializing SDK
60-
We recommend that you keep a reference to the `extole` and share it between activities.
76+
### Event Data
77+
Send Extole events, such as registers, signups, conversions, account openings, etc:
78+
```
79+
extole.sendEvent("my_event", {"key" to "values"})
80+
```
81+
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.
6182

83+
### CTA Content
84+
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:
6285
```
63-
val extole = Extole.builder()
64-
.withPersistance(SharedPreferencesPersistance(context))
65-
.withAppName("YOUR-APPLICATION-NAME")
66-
.addData("version", "YOUR-APPLICATION-VERSION")
67-
.build()
86+
val (zone, campaign) = extole.fetchZone("cta_prefetch")
87+
runOnUiThread {
88+
findViewById<EditText>(R.id.cta_text)
89+
.setText(zone?.get("text").toString(),TextView.BufferType.NORMAL)
90+
findViewById<EditText>(R.id.cta_image)
91+
.setText(zone?.get("image").toString(),TextView.BufferType.NORMAL)
92+
zone.sendEvent("cta_clicked")
93+
}
94+
6895
```
6996

70-
### Rendering content for a menu item example
97+
## 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`.
98+
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.
99+
100+
## Advanced Usage
101+
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 [email protected].
71102

72-
Allowing the marketer to manage the call to action messaging to align with the marketing campaign.
103+
### Deeplink integration
104+
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.
105+
Deep link example:
73106

74107
```
75-
GlobalScope.launch {
76-
val (zone, campaign) = extole.getZone("promotional_menu")
77-
runOnUiThread {
78-
findViewById<EditText>(R.id.promotional_menu_item).setText(
79-
zone.get("menu_text").toString(), TextView.BufferType.NORMAL
80-
)
81-
}
108+
DeepLinkListener { linkProperties, error ->
109+
GlobalScope.launch {
110+
ServiceLocator.getExtole(this@DeeplinkActivity)
111+
extole.sendEvent("deeplink", linkProperties)
112+
}
82113
}
83114
```
115+
Extole will be able to react to this based on the Campaign configuration in[ ](http://my.extole.com/)My Extole.
84116

85-
This example assumes you have configured the 'promotional_menu' zone with 'menu_text' in Extole.
86-
87-
### WebView example
88-
89-
A webview is a convenient way to support a rich campaign experience, while minimizing mobile development. Extole,
90-
supports tracking important events in the webview, like tracking native sharing events.
117+
### Configuring Actions from Events
118+
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.
119+
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:
91120

92121
```
93-
GlobalScope.launch {
94-
val (zone, campaign) = extole.getZone("promotional_menu")
95-
runOnUiThread {
96-
val menuItemButton = findViewById<Button>(R.id.menu_item_button)
97-
menuItemButton.text = zone.get("menu_item_text").toString()
98-
menuItemButton.setOnClickListener {
99-
val intent = Intent(this@Activity, WebViewActivity::class.java)
100-
intent.putExtra("webViewItem", menuItemButton.get("webViewItem").toString())
101-
startActivity(intent)
122+
{
123+
"operations": [
124+
{
125+
"conditions": [
126+
{
127+
"type": "EVENT",
128+
"event_names": [
129+
"cta_tap"
130+
]
131+
}
132+
],
133+
"actions": [
134+
{
135+
"type": "VIEW_FULLSCREEN",
136+
"zone_name": "microsite"
102137
}
138+
]
103139
}
140+
]
104141
}
105142
```
106143

107-
Where `WebViewActivity` layout contains a `WebView` and when Activity is initilized we are doing:
108-
109-
```
110-
val extras = intent.extras
111-
val webViewItem = extras!!.getString("webViewItem").orEmpty()
144+
### Supported Actions
145+
The following types of actions are supported by default in our SDK.
146+
<table>
147+
<tr>
148+
<td><strong>Action Name</strong>
149+
</td>
150+
<td><strong>Description</strong>
151+
</td>
152+
</tr>
153+
<tr>
154+
<td><code>PROMPT</code>
155+
</td>
156+
<td>Display a pop-up notification native to iOS. For example, this could appear when a discount or coupon code has been successfully applied.
157+
</td>
158+
</tr>
159+
<tr>
160+
<td><code>NATIVE_SHARING</code>
161+
</td>
162+
<td>Open the native share sheet with a predefined message and link that customers can send via SMS or any enabled social apps.
163+
</td>
164+
</tr>
165+
<tr>
166+
<td><code>VIEW_FULLSCREEN</code>
167+
</td>
168+
<td>Trigger a full screen mobile web view. For example, this could be your microsite as configured in My Extole to display the share experience.
169+
</td>
170+
</tr>
171+
</table>
172+
173+
### Custom Actions
174+
If you would like to create custom actions beyond our defaults, use the format exhibited in the example below. Please reach out to our Support Team at [[email protected]](mailto:[email protected]) if you have any questions.
175+
176+
#### Example custom action
177+
In this example, describe how to create example pop up, asking question sending event to extole, returns JSON, pulling custom action value
178+
179+
```
180+
class CustomAction(@Se±rializedName("custom_action_value") val customParameter: String) : Action {
181+
182+
companion object {
183+
val ACTION_TITLE = "CUSTOM_ACTION"
184+
}
112185
113-
val webView = findViewById<WebView>(R.id.webview)
114-
val context: Context = this
115-
GlobalScope.launch {
116-
val webViewBuilder = extole.webViewBuilder(webView)
117-
runOnUiThread {
118-
val extoleWebView = webViewBuilder.create()
119-
extoleWebView.load("microsite")
186+
override suspend fun execute(event: AppEvent, extole: ExtoleInternal) {
187+
extole.getData()["custom_action_key"] = "custom_action_value"
120188
}
189+
190+
override fun getType(): Action.ActionType = Action.ActionType.CUSTOM
191+
192+
override fun getTitle(): String = ACTION_TITLE
121193
}
122-
```
123194
124-
This example assumes you have configured a 'microsite' zone to server content.
195+
```
125196

197+
#### Registering a custom action
198+
```
199+
Extole.registerAction("CUSTOM_ACTION", CustomAction::class.java)
200+
```
126201

127-
### Sending events
202+
## Appendix
203+
### Advanced Actions
204+
#### Load Operations
128205

129206
```
130-
extole.sendEvent("purchase", mapOf("order_id" to "123", "cart_value" to "120.30"))
207+
{
208+
"type": "LOAD_OPERATIONS",
209+
"zones": [
210+
"<zone_name>"
211+
],
212+
"data": {
213+
"key": "value"
214+
}
215+
}
131216
```
132217

133-
### Sharing via Email through Extole
218+
#### Fetch
219+
```
220+
{
221+
"type": "FETCH",
222+
"zones": [
223+
"<zone_name_1>",
224+
"<zone_name_2>"
225+
]
226+
}
227+
```
134228

229+
#### Set Log Level
135230
```
136-
GlobalScope.launch {
137-
val (_, campaign) = extole.getZone("promotional_email")
138-
campaign.emailShare(recipient, subject, message);
231+
{
232+
"type": "SET_LOG_LEVEL",
233+
"log_level": "WARN"
139234
}
140235
```

0 commit comments

Comments
 (0)