Overview

Basic Integration

Download SDK

 Add Mobibox SDK to your android project

• Goto File -> New -> New Module -> then select Import .JAR/.AAR Package

• After that it will ask you for AAR path, so select the sdk path and click on finish.

• Then it will take few second to add it on your project

• Here you can see modules and you need to select  host app like in screenshot

• Then you need to click on Dependencies tab, you can see there list of dependencies

• In that tab you need to click on + icon and then click in Module dependency like below screenshot

• There you can see AAR file and you need to select it and click ok on dependency dialog then also click on ok on project structure dialog.

• After that it will take few second to sync project.

• After sync finish you need to open app level gradle file where you can see below line :

implementation project(':paymentsdk-3.906)

Additional Dependencies for the project

implementation 'com.android.support:multidex:1.0.2'
implementation 'com.squareup.okhttp3:okhttp:3.8.0'
implementation 'com.google.android.gms:play-services-analytics:12.0.1'
implementation 'com.google.android.gms:play-services-base:12.0.1'
implementation 'com.google.android.gms:play-services-identity:12.0.1'
implementation 'com.google.android.gms:play-services-auth:12.0.1'
implementation 'com.google.android.gms:play-services-auth-api-phone:12.0.1'
implementation 'com.google.code.gson:gson:2.4'
implementation 'com.adjust.sdk:adjust-android:4.12.4'
implementation 'com.android.installreferrer:installreferrer:1.0'

implementation project(':paymentsdk-3.903')

Add permissions

In the Package Explorer open the AndroidManifest.xml of your Android project and add the following permissions.

<uses-permission android:name="android.permission.INTERNET"/> 
<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
<uses-permission android:name="android.permission.SYSTEM_ALERT_WINDOW" />
<uses-permission android:name="android.permission.READ_PHONE_STATE" />

<!-- permissions for auto-detecting and auto-verifying pin code-- >

<uses-permission android:name="android.permission.READ_SMS" />
<uses-permission android:name="android.permission.RECEIVE_SMS" />

<!-- permissions for Only to be added if MO flow is supported -- >

<uses-permission android:name="android.permission.WRITE_SMS" />
<uses-permission android:name="android.permission.SEND_SMS" />

Add Intent filter to receive SMS

To support auto-detection of Pin code for DCB subscriptions, we need to be able to listen to incoming SMS. In order to do this, we will add a <receiver> to register a broadcast receiver to the manifest XML. We will also add an <intent-filter> to let Android know that we want to launch a specific class when an SMS comes in.

<receiver android:name="com.ma.paymentsdk.broadcast.MA_MessageReceiver" >
    <intent-filter android:priority="1000" >
        <action android:name="android.provider.Telephony.SMS_RECEIVED" />
    </intent-filter>
</receiver>

Add Broadcast Receivers for tracking

Whenever your app is installed on a device, Android broadcasts an Intent containing the Google Play Install referrer. This is an important attribution value which must be passed into Mobibox SDK.

You'll need to configure a BroadcastReceiver which listens for this Intent. This can be done by adding receiver tag inside the application tag in your AndroidManifest.xml.

<!-- INSTALL_REFERRER Receiver-->

<receiver
    android:name=".objects.InstallReceiver"
    android:exported="true" >
    <intent-filter android:priority="1000">
        <action android:name="com.android.vending.INSTALL_REFERRER" />
    </intent-filter>
</receiver>

Since your app contains SDK which needs to know about the Google Play Referrer, you should implement your own BroadcastReceiver. This custom BroadcastReceiver should extract the referrer from the Intent and pass it into each SDK like below:

import android.content.BroadcastReceiver;
import android.content.Context;
import android.content.Intent;

import com.google.android.gms.analytics.CampaignTrackingReceiver;
import com.ma.paymentsdk.broadcast.MA_CampaignTrackingReceiver;

public class InstallReceiver extends BroadcastReceiver {
    @Override
    public void onReceive(Context context, Intent intent) {
       
       
        new MA_CampaignTrackingReceiver().onReceive(context, intent);
       
        // Google Analytics
        new CampaignTrackingReceiver().onReceive(context, intent);

    }
}

Basic Setup

a. Define set of keys and identifiers related to your app by adding the following meta-data tag inside the <application> element in AndroidManifest.xml.

<meta-data android:name="com.facebook.sdk.ApplicationId" android:value="@string/facebook_app_id" />

<meta-data android:name="com.ma.ServiceId" android:value="@string/serviceId"/>
<meta-data android:name="com.ma.ClientGuid" android:value="@string/ClientGuid"/>
<meta-data android:name="com.ma.ClientKey" android:value="@string/ClientKey"/>
<meta-data android:name="com.ma.AppToken" android:value="@string/appToken" />

<!-- campaignId is used only in case of offline campaigns -->
<meta-data android:name="com.ma.Apk_CampaignId" android:value="@string/ApkCampaignid"/>

b. Fill in the values of your keys and identifiers in strings.xml file. (To be provided by MobileArts).

<string name="serviceId"></string>
<string name="ClientGuid"></string>
<string name="ClientKey"></string>
<string name="appToken"></string>
<string name="facebook_app_id"></string>

<string name="ApkCampaignid"></string>

c. Inside the<application> element in AndroidManifest.xml, define the below activities used from Mobibox SDK (Subscription related activities).

<activity
    android:name="com.ma.paymentsdk.MA_BillingActivity"
    android:theme="@style/Theme.AppCompat.Light.DarkActionBar.NoActionBar"
    android:configChanges="orientation|screenSize|keyboard|keyboardHidden" >
</activity>

<activity
    android:name="com.ma.paymentsdk.SelectCountryActivity"
    android:theme="@style/Theme.AppCompat.Light.DarkActionBar"
    android:screenOrientation="portrait"/>

Initialize the SDK

We recommend using a global android Application class to initialize Mobibox SDK. If you don't have one in your app already, follow these steps:

a. Create a class “GlobalApplication” that extends Application.

b. Open the AndroidManifest.xml file of your app and locate the <application> element.

c. Add the attribute android:name and set it to the name of your new application class

prefixed by a dot, so the manifest file is configured as:

<application
    android:name=".GlobalApplication"
    android:allowBackup="true"
    android:icon="@mipmap/ic_launcher"
    android:label="@string/app_name"
    android:theme="@style/AppTheme"
    tools:replace="icon,label,theme">

d. In your Application class find or create the onCreate method and add the following code to initialize the Mobibox SDK. Depending on whether you build your app for testing or for production, you must enable or disable logs when initializing Mobibox SDK by setting the second parameter to true or false.

import android.content.Context;
import android.support.multidex.MultiDex;
import android.support.multidex.MultiDexApplication;

import io.branch.referral.Branch;

public class GlobalApplication extends MultiDexApplication {

    public static boolean isPremium = false;
    public static boolean isActiveUser = false;
    public static boolean isFreeTrial = false;

    @Override
    protected void attachBaseContext(Context base) {
        super.attachBaseContext(base);
        MultiDex.install(this);
    }

    @Override
    public void onCreate() {
        super.onCreate();
        
           String language = Locale.getDefault().toString();

            MobiboxConfig config = new MobiboxConfig(this, false, language, true);
        
    }

}

Billing setup

a. Use the below code, anywhere in your code to open Billing Activity for your user.

private final int SDK_CODE = 11; 

Intent intent = new Intent(context, MA_BillingActivity.class);
startActivityForResult(intent, SDK_CODE);

b. In the same activity where you opened the billing activity, call onActivityResult to check if payment was successful or not.

@Override
protected void onActivityResult(int requestCode, int resultCode, Intent data) {
   super.onActivityResult(requestCode, resultCode, data);
   if (requestCode == SDK_CODE) {
      if(resultCode == RESULT_OK){
         if (MA_Billing.getBillingStatus(Context)) {
            //User has successfully subscribed
         } else {
            //User did not subscribe
         }
      }
      if (resultCode == RESULT_CANCELED) {
         //User did not subscribe
      }
   }
}

Billing lookup

a. To check if user has subscribed (premium) or not through Mobibox SDK when using the app, you can check the below locale variable.

if (MA_Billing.getBillingStatus(Context)) {
   //User has successfully subscribed
} else {
   //User did not subscribe
}

If user is premium according to the locale variable above, you can check the real-time billing status on the backend of the subscribed user by calling the lookup function (lookup on MSISDN). The activity to call this function, should implement MA_OnLookUp

MA_Lookup lookup = new MA_Lookup();
lookup.LookUpSubscriber(Context);

b. The lookup result will give a clear idea about user’s status, which allow you to handle the permissions as you wish.

public void lookupResult(int status, String Description, Boolean isFreeTrial, String subscriptionDate, String expiryDate) {

   Logcat.e(tag, "User status: " + status + " description: " + Description);
   try {
      //Status values:
      //0 for active users - subscribed and billed users
      //1 for none active users - subscribed users but not billed due to low balance
      //2 for deleted users - unsubscribed users => Open billing Activity
      //3 user not found => Open billing Activity
   } catch (Exception e) {
      //Exception occurred, manage the case as you wish
   }
}

Billing Information

Mobibox SDK provides additional billing information such as: AccountDetails and how-to unsub from the app. These are only applicable if the user is premium.

a. showUnsubDialogFromAPI
MA_Dialogs.showUnsubDialogFromAPI(Context);

b. showMyAccountFromAPI
MA_Dialogs.showMyAccountFromAPI(Context);

Custom Events tracking

SendEvent Function can be called for tracking any event or action you want to track (events should be defined on Mobibox interface first). In the example below, we are tracking whenever user presses on upgrade button.

EventHandler.sendEvent(MA_Constants.UPGRADE_EVENT, tag, "", "", new EventTrackerListener() {
   @Override
   public void onSendEventComplete(JSONObject json) {
   }

   @Override
   public void onSendEventError(String error) {
   }
},context);

Force update app

“Force update app” is a very important feature handled by Mobibox SDK. From backend, you can set if you want to force update the app in a certain country (Maybe some new feature or new operator’s rule needs to be implemented, then only force update concerned country).

If the force Update value is true, then SDK will automatically ask user to update the app before using it and will redirect him to play store link.

Host app can integrate this feature, by checking if the app needed force update and user did not update, then don’t allow user to use the app and close it.

if(MA_Billing.isAppNeedsUpdate(context)) {
   //Means app needs update but user did not update, then close app
   finish();
}

Free version support

Some apps, may or may not, have support for free version (free features or free content). This property can be set from backend (by country) and SDK will store it locally.

This way, host app can know if there is a free version to be granted to user or not.

if (MA_Billing.getIsFreelink(context)){
   //App has free version, so user can still use the service with limited access
} else {
   //App does not have free version, and therefor user cannot use the app -> close the app by finishing the activity
}

MISDN auto-detection

Whenever possible, Mobibox SDK will auto detect MSISDN and make it available to host app.

String phoneNumber = MA_Utility.getPhoneNumber(MainActivity.this);
if (phoneNumber != null && !phoneNumber.isEmpty()){
   //Phone number detected
} else {
   //Phone number couldn't be detected
}

Best practice

The best flow to implement that takes care of all cases (User premium, active, not active, free version availability, should app force update) is listed below:

a. In first activity that gets launched in your app (usually SpalshScreenActivity), first thing to do is to check if user is premium or not (from the locale variable of the SDK).

b. If user is premium, then call lookup to check his subscription status (active, not active, unsubscribed) and according to the lookup result take action. Lookup check is recommended to be done on first launch of the app and then depend on local variables to define users’ status.

c. If user is not premium, then open billing activity to allow user to subscribe.

d. If SDK returns that user subscribed successfully, then unlock premium features (or open portal). If SDK returns that subscription failed, then keep premium features locked (or open portal/close app according to free Version availability of the service).

e. OnLookupResult or onPaymentResult, check if the app needs force update and the user did not update, close the app.

private final int SDK_CODE = 11;
MA_Lookup lookup;

private void firstThingToDo() {

   if (MA_Utility.isOnline(context)) {
      if (Ma_Billing.getBillingStatus(context)) {
         callLookup();
      } else {
         Intent intent = new Intent(context, MA_BillingActivity.class); 
         startActivityForResult(intent, SDK_CODE);
      }
   } else {
      Toast.makeText(context, R.string.no_internet_connexion, Toast.LENGTH_LONG).show();
      finish();
   }
}

private void callLookup() {
   lookup = new MA_Lookup(context);
   lookup.LookUpSubscriber(context);
}

public void lookupResult(int status, String Description, Boolean isFreeTrial, String subscriptionDate, String expiryDate) {

   Logcat.e(tag, "User status: " + status + " description: " + Description);
   if(MA_Billing.isAppNeedsUpdate(context)) {
      //Means app needs update but user did not update, then close app
      finish();
      return;
   }
   try {
      //Status values:
      //0 for active users - subscribed and billed users
      //1 for none active users - subscribed users but not billed due to low balance
      //2 for deleted users - unsubscribed users
      //3 user not found
      if(status == 2 ||status == 3) {
         //unsubscribed or not found users, open billing activity again
         Intent intent = new Intent(context, MA_BillingActivity.class);
         startActivityForResult(intent, SDK_CODE);
      } else if(status == 1) {
         //subscribed users but not billed due to low balance
      } else {
         //active users - subscribed and billed users
      }
   } catch (Exception e) {
      //Exception occurred, manage the case as you wish
   }
}

@Override
protected void onActivityResult(int requestCode, int resultCode, Intent data) {
   super.onActivityResult(requestCode, resultCode, data);
   Logcat.e(tag, "onActivityResult");

   if (requestCode == SDK_CODE) {

      if(MA_Billing.isAppNeedsUpdate(context)){
         finish();
         return;
      }
      if(resultCode == RESULT_OK){
         if (MA_Billing.getBillingStatus(context)) {
            //User has successfully subscribed, and you can grant him access to the premium features/content
         } else {
            //User did not subscribe, check if the app has free version or not
            if (MA_Billing.getIsFreelink(context)){
               //App has free version, so user can still use the service with limited access
            } else {
               //App does not have free version, and there for user cannot use the app -> close the app by finishing the activity
            }
         }
      }
      if (resultCode == RESULT_CANCELED) {
         //Write your code if there's no result
        
      }
    } else if (requestCode == MA_Lookup.RC_READ) {
        

        Logcat.e(tag, "onActivityResult: requestCode == MA_Lookup.RC_READ");
        if (lookup != null) {
            lookup.onActivityResult(requestCode, resultCode, data);
        }

    }        
}

Sample project