Cello for Android

The Cello SDK for Android enables you to add a referral program into your Android app. With a plug-n-play mobile component, your users can easily share their invite link with their friends and network using mobile sharing options convenient for them, receive rewards and get paid out.

Installation

You can install Cello for Android using Gradle or manually. A basic installation takes around 15 minutes but will take a little longer if you want to customize the way the Cello Referral Component is launched.

Compatibility

Cello SDK for Android is compatible with API 21 and up.

SDK size

The size of Cello for Android once installed varies depending on your app’s configuration. Around 7MB is the average size increase we would expect to see if you’re minifying your app correctly.

Setup

Install Cello to see and give your users the option to spread the word from your Android app. Cello for Android supports API 21 and above. Note: We recommend using the latest available compileSdkVersion.

Install Cello

Add the following dependency to your app’s build.gradle file:

Groovy (or Kotlin DSL)

dependencies {
    implementation("so.cello.android:cello-sdk:0.9.1")
}

Also, ensure that Maven Central is added to your root build.gradle:

allprojects {
    repositories {
        mavenCentral()
    }
}

Choose an Environment

In your Cello SDK setup, you have the flexibility to select the environment in which your application will run. This feature is especially useful for different stages of development, such as testing in a development or staging environment before going live in production. The available environments are:

prod (Production) – default
sandbox (Sandbox)

Configuration Steps

In your Android project, open or create res/values/config.xml, then add:

<?xml version="1.0" encoding="utf-8"?>
<resources>
    <string name="cello_env">prod</string>
</resources>

To change the environment, simply replace the value of cello_env. For instance, to set the environment to sandbox:

<string name="cello_env">sandbox</string>

Save and rebuild your project to apply. Using this configuration, the Cello SDK will adapt to the specified environment, allowing for more controlled development and testing processes.

Initialize Cello

In this step, you will need your product ID and a token you have generated for the user, similar when implementing the web based Referral component. Then, initialize Cello by calling the following in the onCreate() method of your application class:

Cello.initialize(this, "YOUR_PRODUCT_ID", token)

Note: If you don’t currently implement a custom application, you’ll need to create one. A custom application looks like this:

Kotlin

class CustomApplication : Application() {
    override fun onCreate() {
        super.onCreate()
        Cello.initialize(this, "YOUR_PRODUCT_ID", token)
    }
}

Java

public class CustomApplication extends Application {
    @Override
    public void onCreate() {
        super.onCreate();
        Cello.initialize(this, "YOUR_PRODUCT_ID", token);
    }
}

Note: Cello SDK must be initialized inside the application onCreate() method. Initializing anywhere else will result in the SDK not behaving as expected and could even result in the host app crashing.

Customize the Cello Referral Component

The Cello SDK allows for various levels of customization to better fit into your app’s design and flow. One of the main components you might want to customize is the Referral component You have two options to launch the referral component:

Default Launcher

If you choose to go with the default launcher, you can call the showFab() method from the Cello SDK to present a Floating Action Button (FAB) within your app. This FAB is pre-styled but may not perfectly match your app’s look and feel.

Cello.client().showFab()

Custom Launcher

If the default launcher does not fit your needs, you can implement your own custom launcher. This could be any UI element like a button, menu item, or even a gesture. To open the Referral component using a custom launcher, you can call Cello.openWidget().

Cello.client().openWidget()

Example using Compose:

Button(onClick = { Cello.client().openWidget() }) {
    Text("Open Referral")
}

Android API

`Cello.initialize()`

Initializes the Cello referral component.

Name	Type	Description	Required
activity	Activity	This is the reference to the MainActivity	Yes
productId	String	Identifier of the product your users will refer	Yes
token	String	Access token generated for the given user	Yes
productUserDetails	ProductUserDetails	Product user details	No
language	String	Initial language of the widget	No

import com.cello.cello_sdk.ProductUserDetails

val productUserDetails = ProductUserDetails(
    firstName = "John",
    lastName = "Doe",
    fullName = "John Doe", 
    email = "john.doe@example.com"
)

Cello.initialize(this, "YOUR_PRODUCT_ID", token, productUserDetails = productUserDetails, language = 'de')

`Cello.showFab()`

Shows the Floating action button or bookmark that launches the Referral Component

Cello.client().showFab()

`Cello.hideFab()`

Hides the Floating action button or bookmark that launches the Referral Component

Cello.client().hideFab()

`Cello.openWidget()`

Opens the referral component.

Cello.client().openWidget()

`Cello.hideWidget()`

Hides the referral component.

Cello.client().hideWidget()

`Cello.getActiveUcc()`

A method to get an active ucc and invite link for the currently logged in user.

val result = Cello.client().getActiveUcc()

`getCampaignConfig()`

Returns campaign config values for the currently logged-in user.

let result = Cello.client().getCampaignConfig()

Returns

campaignConfig

object

The campaign config object:

Show properties

primaryCurrency

string

Primary currency code

revenuePercentage

number

Percentage of attributed new revenue that will be paid as a reward

rewardCap

number

Maximum reward that can be earned per referral

Additional reward for signups to encourage more sharing

newPurchaseBonus

number

Additional reward for purchases to encourage more sharing

newUserDiscountMonth

number

How long new users get a discount

newUserDiscountPercentage

number

The discount new users get

`Cello.changeLanguage()`

A method to change the language of the Referral component at runtime without re-initialising it.

Cello.client().changeLanguage("de")

`Cello.shutdown()`

Shuts down connection to Cello and unmounts the component

Cello.client().shutdown()

Error Handling

Common Error Scenarios

1. Invalid Parameters

What it means: The product ID or token provided during initialization is empty or blank. Error behavior:

SDK initialization is silently skipped
Warning logged: "Initialization skipped: productId and token must not be empty or blank"
No exception thrown

Common causes:

Empty strings for productId or token
Whitespace-only strings

2. Network/API Errors

What it means: The network request to initialize the SDK or update token failed. Error type: RuntimeException("Response not successful") Common causes:

No internet connection
Server errors (5xx responses)
HTTP errors (4xx responses)
Timeout issues
Firewall or proxy blocking requests

3. Activity State Errors

What it means: The Activity is destroyed, finishing, or not available when trying to perform UI operations. Error type: IllegalStateException("Activity is not valid") Error message: "Cannot perform UI operation - Activity is not available or destroyed" Common causes:

Calling SDK methods after Activity is destroyed
Activity finishing during async operations
Attempting UI operations during Activity transitions

4. Initialization Failures

What it means: The SDK failed to initialize due to an error in the initialization process. Error behavior:

Exception passed to callback
Error logged: "Error initializing widget: {exception message}"
Pending operations cleared

Common causes:

Network connectivity issues
Invalid credentials (product ID or token)
Server-side configuration issues

Error Handling Best Practices

1. Always handle both success and error cases:

Cello.initialize(this, productId, token) { config, exception ->
    if (exception != null) {
        // Handle error
        Log.e("Cello", "Error: ${exception.message}")
        showErrorMessage("Unable to initialize referral system")
    } else {
        // Handle success
        Log.d("Cello", "Initialized successfully")
        setupReferralFeatures(config)
    }
}

2. Validate parameters before SDK calls:

fun initializeCello(productId: String, token: String) {
    // Validate product ID
    if (productId.isBlank()) {
        Log.e("Cello", "Product ID cannot be empty")
        showError("Configuration error")
        return
    }

    // Validate token
    if (token.isBlank()) {
        Log.e("Cello", "Token cannot be empty")
        showError("Authentication error")
        return
    }

    // Check Activity state
    if (isFinishing || isDestroyed) {
        Log.e("Cello", "Cannot initialize - Activity is finishing")
        return
    }

    Cello.initialize(this, productId, token) { config, error ->
        // Handle result
    }
}

3. Implement retry logic for network errors:

class CelloManager(private val activity: Activity) {
    private var retryCount = 0
    private val maxRetries = 3

    fun initializeWithRetry(productId: String, token: String) {
        Cello.initialize(activity, productId, token) { config, exception ->
            if (exception != null) {
                handleInitializationError(exception, productId, token)
            } else {
                retryCount = 0
                onInitializationSuccess(config)
            }
        }
    }

    private fun handleInitializationError(
        exception: Exception,
        productId: String,
        token: String
    ) {
        Log.e("Cello", "Initialization error: ${exception.message}")

        // Retry for network errors
        if (exception is RuntimeException && retryCount < maxRetries) {
            retryCount++
            val delay = (2000L * retryCount) // Linear backoff

            Handler(Looper.getMainLooper()).postDelayed({
                Log.d("Cello", "Retrying initialization (attempt $retryCount)")
                initializeWithRetry(productId, token)
            }, delay)
        } else {
            // Max retries reached or non-recoverable error
            retryCount = 0
            showFinalError("Failed to initialize after $maxRetries attempts")
        }
    }
}

4. Track initialization state:

class CelloStateManager(private val activity: Activity) {
    private var initializationState = InitState.NOT_INITIALIZED

    enum class InitState {
        NOT_INITIALIZED,
        INITIALIZING,
        INITIALIZED,
        FAILED
    }

    fun initialize(productId: String, token: String) {
        if (initializationState == InitState.INITIALIZING) {
            Log.w("Cello", "Initialization already in progress")
            return
        }

        initializationState = InitState.INITIALIZING

        Cello.initialize(activity, productId, token) { config, exception ->
            if (exception != null) {
                initializationState = InitState.FAILED
                Log.e("Cello", "Initialization failed")
            } else {
                initializationState = InitState.INITIALIZED
                Log.d("Cello", "Initialization successful")
            }
        }
    }

    fun showWidget() {
        when (initializationState) {
            InitState.NOT_INITIALIZED -> {
                Log.w("Cello", "SDK not initialized")
            }
            InitState.INITIALIZING -> {
                Log.w("Cello", "SDK still initializing")
            }
            InitState.FAILED -> {
                Log.e("Cello", "Cannot show widget - initialization failed")
            }
            InitState.INITIALIZED -> {
                Cello.openWidget()
            }
        }
    }
}

5. Handle Activity lifecycle properly:

class MainActivity : AppCompatActivity() {
    private var isCelloReady = false

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        initializeCello()
    }

    private fun initializeCello() {
        Cello.initialize(this, productId, token) { config, error ->
            if (error == null && !isFinishing && !isDestroyed) {
                isCelloReady = true
            }
        }
    }

    fun performCelloAction() {
        // Always check Activity and SDK state
        if (isFinishing || isDestroyed) {
            Log.w("Cello", "Activity is finishing - cannot perform action")
            return
        }

        if (!isCelloReady) {
            Log.w("Cello", "SDK not ready")
            return
        }

        Cello.openWidget()
    }

    override fun onDestroy() {
        super.onDestroy()
        if (isFinishing) {
            isCelloReady = false
            Cello.shutdown()
        }
    }
}

Getting Help

If you encounter an error you can’t resolve:

Check the error scenario in the reference above
Verify your integration follows the code examples
Check logcat for detailed error messages: adb logcat | grep cello-sdk
Verify network connectivity and firewall settings
Ensure product ID and token are valid and not empty
Check Activity lifecycle (not finishing or destroyed)
Contact Cello support with:
- Full error message and stack trace from logcat
- Steps to reproduce
- SDK version
- Android OS version and device model
- Network conditions when error occurred

SDKs

Client-Side SDKs

Mobile SDKs

Cello for Android

Installation

Compatibility

SDK size

Setup

Install Cello

Groovy (or Kotlin DSL)

Choose an Environment

Configuration Steps

Initialize Cello

Kotlin

Java

Customize the Cello Referral Component

Default Launcher

Custom Launcher

Android API

`Cello.initialize()`

`Cello.showFab()`

`Cello.hideFab()`

`Cello.openWidget()`

`Cello.hideWidget()`

`Cello.getActiveUcc()`

`getCampaignConfig()`

Returns

`Cello.changeLanguage()`

`Cello.shutdown()`

Error Handling

Common Error Scenarios

1. Invalid Parameters

2. Network/API Errors

3. Activity State Errors

4. Initialization Failures

Error Handling Best Practices

Getting Help

SDKs

Client-Side SDKs

Mobile SDKs

​Installation

​Compatibility

​SDK size

​Setup

​Install Cello

​Groovy (or Kotlin DSL)

​Choose an Environment

​Configuration Steps

​Initialize Cello

​Kotlin

​Java

​Customize the Cello Referral Component

​Default Launcher

​Custom Launcher

​Android API

​Cello.initialize()

​Cello.showFab()

​Cello.hideFab()

​Cello.openWidget()

​Cello.hideWidget()

​Cello.getActiveUcc()

​getCampaignConfig()

​Returns

​Cello.changeLanguage()

​Cello.shutdown()

​Error Handling

​Common Error Scenarios

​1. Invalid Parameters

​2. Network/API Errors

​3. Activity State Errors

​4. Initialization Failures

​Error Handling Best Practices

​Getting Help

Installation

Compatibility

SDK size

Setup

Install Cello

Groovy (or Kotlin DSL)

Choose an Environment

Configuration Steps

Initialize Cello

Kotlin

Java

Customize the Cello Referral Component

Default Launcher

Custom Launcher

Android API

`Cello.initialize()`

`Cello.showFab()`

`Cello.hideFab()`

`Cello.openWidget()`

`Cello.hideWidget()`

`Cello.getActiveUcc()`

`getCampaignConfig()`

Returns

`Cello.changeLanguage()`

`Cello.shutdown()`

Error Handling

Common Error Scenarios

1. Invalid Parameters

2. Network/API Errors

3. Activity State Errors

4. Initialization Failures

Error Handling Best Practices

Getting Help