Tonos Android SDK

Version: 1.1.3

---

This service allows you to add Tonos into your Android application. This section of the documentation provides detailed steps on how to succesfully complete this task.

Requirements

Item	Notes
Android Studio	Download & Install Android Studio.
Android 4.4 (API 19)	Your app must be leveraging at least this minimum OS version.
Tonos License	Request a license by contacting Tonos at tonos@gjirafa.tech

Adding the Tonos SDK

1. From Android Studio, open your project.
2. Open settings.gradle if you're using dependency resolution management. Otherwise, open a project-level build.gradle file.
3. Add the necessary repositories.

repositories {
    ...
    maven { url 'https://pkgs.dev.azure.com/gjirafadev/_packaging/AndroidResources/maven/v1' }
        maven {
            url 'https://pkgs.dev.azure.com/gjirafadev/Tonos/_packaging/AndroidTonos/maven/v1'
            credentials {
                username "{Your username}"
                password "{Your password}"
            }
        }
}

NOTE

Replace the username and password in order for Tonos to compile successfully.

4. Navigate to the build.gradle app level under the dependencies folder. Add the following code snippet.

build.gradle

implementation "tech.gjirafa:tonos:{TAG}"

NOTE

Replace {TAG} with the latest version of the Tonos SDK.

5. In the app level build.gradle file, configure compileOptions to support Java 8 language, multidex, and also configure the appAuthRedirectScheme.

build.gradle

android {
    defaultConfig {
        ...
        minSdkVersion 19
        multiDexEnabled true
        android.defaultConfig.manifestPlaceholders = ['appAuthRedirectScheme': '{YourApplicationId}']
    }
    ...
    compileOptions {
        sourceCompatibility = '1.8'
        targetCompatibility = '1.8'
    }
}

NOTE

Note: Replace {YourApplicationId} for appAuthRedirectScheme

6. Sync Gradle

You have now successfully added the Tonos SDK into your application

Configuring the Tonos SDK

In order to complete the Tonos SDK import process, you must complete the following steps.

1. Call Tonos.setup() on your running activity.

Parameter	Description
appCompatActivity	Activity in which you'll use Tonos
appId	Provided from Tonos when setting up your application

The code snippets below provide information on how to execute this process using either Kotlin or Java.

Kotlin

class YourActivity : AppCompatActivity(R.layout.activity_demo) {

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        Tonos.setup(appCompatActivity = this, appId = "appId")
    }
}

Java

public class YourActivity extends AppCompatActivity {

    @Override
    protected void onCreate(@Nullable Bundle savedInstanceState) {
        super.onCreate(savedInstanceState);
        setContentView(R.layout.activity_demo);
        Tonos.INSTANCE.setup(this, "appId");
    }
}

NOTE

Replace the appId parameter with your application ID

2. Call Tonos.auth.onActivityResult() by overriding the onActivityResult() of your running activity.

Parameter	Description
requestCode	Found onActivityResult() response
data	Found onActivityResult() response

The code snippets below provide information on how to execute this process using either Kotlin or Java.

Kotlin

override fun onActivityResult(requestCode: Int, resultCode: Int, data: Intent?) {
    super.onActivityResult(requestCode, resultCode, data)
    // Handling onActivityResult for authenticator login/logout :)
    Tonos.auth.onActivityResult(requestCode, data)
}

Java

@Override
protected void onActivityResult(int requestCode, int resultCode, @Nullable Intent data) {
    super.onActivityResult(requestCode, resultCode, data);
    // Handling onActivityResult for authenticator login/logout :)
    Tonos.INSTANCE.getAuth().onActivityResult(requestCode, data);
}

Displaying offers

In order to display offers in your application from Tonos, you must invoke the Tonos.fetchOffer() function.

The table below describes the parameters of this function.

Param	Type	Description
contentId	String	Used to display offers based on it. One contentId represents one page.
container	View (Optional)	Used to display the offer if the offer we're displaying is an inline offer.
fetchOfferDelegate	FetchOfferDelegate (Optional)	Used to invoke events back to the fetchOffer() method by letting </> know if the offer has loaded successfully or has failed to load.

The code snippets below provide information on how to execute this process using either Kotlin or Java.

Kotlin

Tonos.fetchOffers("YourContentId", yourContainerView, object : FetchOfferDelegate {
    override fun onStateChanged(state: FetchOfferState) {
        if (state == FetchOfferState.OFFER_FAILED_TO_FETCH) {
            // Failed to fetch offer
        } else {
            // Offer loaded successfully
        }
    }
})

Java

Tonos.INSTANCE.fetchOffers("YourContentId", yourContainerView, state -> {
    if (state == FetchOfferState.OFFER_FAILED_TO_FETCH) {
        Toast.makeText(this, "Offer failed to load", Toast.LENGTH_SHORT).show();
    }
});

NOTE

Replace the contentId & containerView with your own values.

Additionally, you can invoke the Tonos.stopOffer() in order to dismiss any modal showing offers & cancel the last fetching offer. This is usually used when you start fetchOffer() and the user navigates back to previous page, in which case we need to stop fetching the last offer & dismiss if it has shown already.

The code snippets below provide information on how to execute this process using either Kotlin or Java.

Kotlin

Tonos.stopOffer()

Java

Tonos.INSTANCE.stopOffer();

Loader customization

If you'd like to customize or enable/disable provided loader, you can use the following functions:

Tonos.setUseLoader

Param	Type	Description
useLoader	Boolean	Enable or disable loader.

The code snippets below provide information on how to execute this process using either Kotlin or Java.

Kotlin

Tonos.setUseLoader(true)

Java

Tonos.INSTANCE.setUseLoader(true);

Tonos.setLoaderStyle()

Param	Type	Description
loaderStyle	LoaderStyle	Data class in which you can change values in order to modify the loader.

Param	Type	Description	Default Value
backgroundOverlayColor	Int	Set your desired background overlay color.	"#103e3e3e".toColorInt()
cardBackgroundColor	Int	Set your desired card background color.	"#FFFFFF".toColorInt()
cardCornerRadius	Int	Set your desired card corner radius.	15
indicatorColor	Int	Set your desired indicator color.	"#000000".toColorInt()

The code snippets below provide information on how to execute this process using either Kotlin or Java.

Kotlin

Tonos.setLoaderStyle(LoaderStyle(
    backgroundOverlayColor = "103e3e3e".toColorInt(),
    cardBackgroundColor = "FFFFFF".toColorInt(),
    cardCornerRadius = 12,
    indicatorColor = "#000000".toColorInt()
))

Java

Tonos.INSTANCE.setLoaderStyle(new LoaderStyle(
    Color.parseColor("#103e3e3e"),
    Color.parseColor("#FFFFFF"),
    12,
    Color.parseColor("#000000")
));

Analytics

When users interact with offers, their actions trigger different events. Below you will find some methods of listening to these events listed along with a desription for each of them.

Implementing the delegate

The code snippets below provide information on how to execute this process using either Kotlin or Java.

Kotlin

Tonos.setStateDelegate(object: TonosStateDelegate {
    override fun onStateChanged(event: TonosEvent<Any>) {
        if (event.state == TonosState.ACCESSIBLE) {
            // Tonos is ready for use
        }
    }
})

Java

Tonos.INSTANCE.setStateDelegate(event -> {
    if (event.getState() == TonosState.ACCESSIBLE) {
        // Tonos is ready for use.
    }
});

---

You can also listen for events in a class level. In order to do so, follow these instructions.

1. On the onCreate() method of your fragment/activity, add the following code snippet.

Kotlin

Tonos.setStateDelegate(this)

Java

Tonos.INSTANCE.setStateDelegate(this);

2. Implement the delegate on our class.

Kotlin

class DemoActivity : AppCompatActivity(R.layout.activity_demo), TonosStateDelegate {
    ...
}

Java

public class DemoJavaActivity extends AppCompatActivity implements TonosStateDelegate {
    ...
}

3. Override the onStateChanged() method.

Kotlin

override fun onStateChanged(event: TonosEvent<Any>) {
    if (event.state == TonosState.ACCESSIBLE) {
        // Tonos ready for use.
    }
}

Java

@Override
public void onStateChanged(@NonNull TonosEvent<?> event) {
    if (event.getState() == TonosState.ACCESSIBLE) {
       // Tonos ready for use.
    }
}

Tonos events

Param	Type	Description
state	TonosState	Notifies user about different states (Check TonosState model table below).
value	Any	If there are any data available which can be passed to our user, they'll be done using a value parameter.

TonosState

ACCESSIBLE
Event	ACCESSIBLE
Description	Fired wen Tonos is ready for use.
Return Type
APP_INITIALIZE
Event	APP_INITIALIZE
Description	Fired when the application is initialized.
Return Type
PAGE_INITIALIZE
Event	PAGE_INITIALIZE
Description	Fired when the page is initialized.
Return Type
LOGIN_SHOW
Event	LOGIN_SHOW
Description	Fired when the login form is shown.
Return Type
LOGIN_SUCCESS
Event	LOGIN_SUCCESS
Description	Fired when the login process is successful.
Return Type
OFFER_SHOWN
Event	OFFER_SHOWN
Description	Fired when the offer is shown.
Return Type
OFFER_CLOSED
Event	OFFER_CLOSED
Description	Fired when the offer is closed.
Return Type
CHECKOUT_SHOW
Event	CHECKOUT_SHOW
Description	Fired when the checkout for is shown.
Return Type
CHECKOUT_ABANDONED
Event	CHECKOUT_ABANDONED
Description	Fired when the checkout process is abandoned.
Return Type
CHECKOUT_SUCCESS
Event	CHECKOUT_SUCCESS
Description	Fired when the checkout process is successful.
Return Type
CHECKOUT_FAILED
Event	CHECKOUT_FAILED
Description	Fired when the checkout process fails.
Return Type
PLAN_SELECTED
Event	PLAN_SELECTED
Description	Fired when a subscription plan is selected.
Return Type
PAYMENT_SHOW
Event	PAYMENT_SHOW
Description	Fired when a payment is shown.
Return Type
FAILED_TO_INITIALIZE_APP
Event	FAILED_TO_INITIALIZE_APP
Description	Fired when the aplication failed to initialize.
Return Type
FAILED_FETCHING_CONFIGURATION_FROM_AUTHORITY
Event	FAILED_FETCHING_CONFIGURATION_FROM_AUTHORITY
Description	Fired when the configuration fetching from authority fails.
Return Type
AUTHENTICATOR_READY
Event	AUTHENTICATOR_READY
Description	Fired when the authenticator is ready.
Return Type
FAILED_TO_USE_AUTHENTICATOR_SERVICE
Event	FAILED_TO_USE_AUTHENTICATOR_SERVICE
Description	Fired when the authenticator service fails to use.
Return Type
FAILED_FETCHING_TOKEN
Event	FAILED_FETCHING_TOKEN
Description	Fired when the token fails to be fetched.
Return Type
FAILED_LOGGING_OUT_USER
Event	FAILED_LOGGING_OUT_USER
Description	Fired when the logout process fails.
Return Type
STARTING_BILLING_CONNECTION
Event	STARTING_BILLING_CONNECTION
Description	Fired when the billing connection starts.
Return Type
BILLING_SETUP_FINISHED
Event	BILLING_SETUP_FINISHED
Description	Fired when the billing setup finishes.
Return Type
BILLING_SERVICE_DISCONNECTED
Event	BILLING_SERVICE_DISCONNECTED
Description	Fired when the billing service is disconnected.
Return Type
STARTING_AUTHENTICATOR
Event	STARTING_AUTHENTICATOR
Description	Fired when the authenticator starts.
Return Type
PROCESSING_AUTHENTICATOR_RESULTS
Event	PROCESSING_AUTHENTICATOR_RESULTS
Description	Fired when the authenticator is processing results.
Return Type
FETCHING_CONSUMABLE_PURCHASE_HISTORY
Event	FETCHING_CONSUMABLE_PURCHASE_HISTORY
Description	Fired when the consumable purcahse history is being fetched.
Return Type
FETCHING_NON_CONSUMABLE_PURCHASE_HISTORY
Event	FETCHING_NON_CONSUMABLE_PURCHASE_HISTORY
Description	Fired when the non consumable history is being fetched.
Return Type
FETCHING_PURCHASE_HISTORY
Event	FETCHING_PURCHASE_HISTORY
Description	Fired when the purchase history is being fetched.
Return Type
STARTING_ACKNOWLEDGE_PURCHASE
Event	STARTING_ACKNOWLEDGE_PURCHASE
Description	Fired when the acknowledge purchase is starting.
Return Type
STARTING_CONSUME_PURCHASE
Event	STARTING_CONSUME_PURCHASE
Description	Fired when the consume purchase is starting.
Return Type
FETCHING_PRODUCT_DETAILS_FROM_STORE
Event	FETCHING_PRODUCT_DETAILS_FROM_STORE
Description	Fired when the product details from the store are being fetched.
Return Type
FAILED_FETCHING_PRODUCT_DETAILS
Event	FAILED_FETCHING_PRODUCT_DETAILS
Description	Fired when the product details failed to be fetched.
Return Type
STARTING_PURCHASE_FLOW
Event	STARTING_PURCHASE_FLOW
Description	Fired when the purchase flow is starting.
Return Type
FAILED_TO_FETCH_OFFER
Event	FAILED_TO_FETCH_OFFER
Description	Fired when the offer failed to be fetched.
Return Type
FAILED_TO_FETCH_TEMPLATE
Event	FAILED_TO_FETCH_TEMPLATE
Description	Fired when the offer template failed to be fetched.
Return Type
FAILED_TO_FETCH_CHECKOUT
Event	FAILED_TO_FETCH_CHECKOUT
Description	Fired when the checkout failed to be fetched.
Return Type
FAILED_TO_PROCESS_PURCHASE
Event	FAILED_TO_PROCESS_PURCHASE
Description	Fired when the purchase was not processed.
Return Type
CLOSE_OFFER_MODAL_REQUESTED
Event	CLOSE_OFFER_MODAL_REQUESTED
Description	Fired when the requested offer modal is closed.
Return Type

Additional methods

We also offer additional methods for Store & Auth. Methods we provide are:

• Auth
  • isAuthReady()
  • startAuthenticator()
  • endSession()
• Store
  • isBillingClientReady()
  • isConnected()
  • startConnection()
  • endConnection()
  • getProduct()
  • buyProduct()
  • State
    • acknowledgePurchase()
    • consumePurchase()
  • History
    • fetchNonConsumablePurchaseHistory()
    • fetchConsumablePurchaseHistory()
    • fetchPurchaseHistory()