Crobox SDK for Android
This is an asynchronous SDK kit for consuming Crobox API for android applications. Written in Kotlin from the ground up.
First add the dependency to your project:
repositories {
mavenCentral()
}
dependencies {
implementation("com.crobox.sdk:crobox-sdk-android:$crobox-sdk-android_version")
}
First configure and create a Crobox
singleton as below, where
containerId
should be assigned by CroboxvisitorId
should be unique for visitors. It must stay the same across the user's session (or longer if preferred)userId
should optionally be used to link the current visitor with client's user management system, if exists
import com.crobox.sdk.common.LocaleCode
import com.crobox.sdk.core.Crobox
import com.crobox.sdk.config.CroboxConfig
import com.crobox.sdk.data.model.*
import com.crobox.sdk.domain.*
import com.crobox.sdk.presenter.*
import java.util.UUID
val croboxInstance = Crobox.getInstance(
CroboxConfig(
containerId = "xlrc9t",
visitorId = UUID.randomUUID(),
userId = "JohnDoe"
)
)
RequestQueryParams contains page specific parameters, shared by all requests fired from the same page/view. It must be recreated when the page/view is displayed.
val overviewPageParams = RequestQueryParams(
viewId = UUID.randomUUID(),
pageType = PageType.PageOverview
)
For sending events, use the xyzEvent
APIs exposed by the Crobox instance.
Events might also take event specific parameters:
croboxInstance.clickEvent(
overviewPageParams,
clickQueryParams = ClickQueryParams(
productId = "0001ABC",
price = 1.0,
quantity = 1
),
eventCallback = object : EventCallback {
override fun onSuccess(dictionary: Map<String, String>) {
Log.d("EventView onSuccess", dictionary.toString())
}
override fun onError(msg: String?) {
Log.d("EventView onError", "" + msg)
}
}
)
For retrieving promotions for zero, one or more products, use the specific PlaceholderId that is configured with specific page types and linked to campaigns via Crobox Admin App.
val promotionsCallback = object : PromotionCallback {
override fun onPromotions(response: PromotionsResponse?) {}
override fun onError(msg: String?) {}
}
val impressions: List<String> = listOf("001ABC", "002DEF")
croboxInstance.promotions(
placeholderId = 1,
queryParams = overviewPageParams,
impressions = impressions,
promotionCallback = promotionsCallback
)
// Requesting for a promotion from a product detail page with another placeholderId for a single product
croboxInstance.promotions(
placeholderId = 2,
queryParams = detailPageParams,
impressions = listOf("001ABC"),
promotionCallback = promotionsCallback
)
// Requesting for a promotion without a product, eg. from a checkout page
croboxInstance.promotions(
placeholderId = 3,
queryParams = checkoutPageParams,
promotionCallback = promotionsCallback
)
object : PromotionCallback {
override fun onPromotions(response: PromotionsResponse) {
val context = response.context
val promotions = response.promotions
val visitorId = context.visitorId
val sessionId = context.sessionId
val groupName = context.groupName ?: ""
for (campaign in context.campaigns) {
val campaignId = campaign.id
val campaignName = campaign.name
val variantId = campaign.variantId
val variantName = campaign.variantName
val control = campaign.control
}
for (promotion in promotions) {
val promotionId = promotion.id
val campaignId = promotion.campaignId
val variantId = promotion.variantId
val productId = promotion.productId ?: ""
promotion.content?.let { content: PromotionContent ->
val messageId = content.messageId
val componentName = content.component
val configMap = content.config
for (c in configMap) {
val configKey = c.key
val configValue = c.value
}
promotion.content?.contentConfig()?.let {
when (it) {
is SecondaryMessaging -> {
val name = it.name
val text = it.text
val fontColor = it.fontColor
val fontColorAndroid = it.fontColorAndroid() ?: Color.valueOf(Color.WHITE)
}
is TextBadge -> {
val name = it.name
val text = it.text
val fontColor = it.fontColor
val borderColor = it.borderColor
val backgroundColor = it.backgroundColor
val fontColorAndroid = it.fontColorAndroid() ?: Color.valueOf(Color.WHITE)
val borderColorAndroid = it.borderColorAndroid() ?: Color.valueOf(Color.WHITE)
val backgroundColorAndroid = it.backgroundColorAndroid() ?: Color.valueOf(Color.WHITE)
}
is ImageBadge -> {
val name = it.name
val image = it.image
val altText = it.altText
}
}
}
}
}
}
}
Name | Type | Description |
---|---|---|
context | PromotionContext | The context about campaigns |
promotions | List | The list of promotions calculated |
Name | Type | Description |
---|---|---|
sessionId | UUID | Session ID |
visitorId | UUID | Visitor ID |
groupName | String? | The list of campaign and variant names, combined |
campaigns | List | The list of ongoing campaigns |
Name | Type | Description |
---|---|---|
id | String | Campaign ID |
name | String | Campaign Name |
variantId | String | There is a ratio that determines the amount of traffic exposed to this campaign (or is allocated to the control group) between Crobox and Control group. Variant id refers to the variant which this promotion belongs to and is used for debugging |
variantName | String | Name of the Campaign Variant |
control | Boolean | Indicates if the variant is allocated to the control group |
Name | Type | Description |
---|---|---|
id | String | Unique id for this promotion |
productId | String? | Product ID if requested |
campaignId | Int | The campaign which this promotion belongs to |
variantId | Int | ID of the variant that this promotion is assigned to |
content | PromotionContent? | Promotion Content |
Name | Type | Description |
---|---|---|
messageId | String | As Campaigns might have alternative messages, Message Id identifies the message assigned to this promotion |
componentName | String | Component Name |
config | Map<String, String> | Map of all visual configuration items, managed via Crobox Admin app. Example: Map("Text1_text" : "Best Seller", "Text1_color" : "#0e1111") |
contentConfig() | PromotionContentConfig? | Returns component configuration if an Image, Text Badge or Secondary Messaging is available as compliant. Requires prior configuration setup in Crobox platform |
Name | Type | Description |
---|---|---|
image | String | Image URL |
altText | String? | Alternate text |
Name | Type | Description |
---|---|---|
text | String | Text message |
fontColor | String | Font color |
backgroundColor | String? | Optional background color |
borderColor | String? | Optional border color |
Name | Type | Description |
---|---|---|
text | String | Text message |
fontColor | String | Font color |
See test app for various samples