SUnit SDK Documentation(Android) - sunitsdk/SUnitDemo GitHub Wiki

This document describes the service content of the SUnit Aggregation SDK and the technical integration method.

The SUnit SDK is a package of commercial solutions provided by SHAREit to game partners, including an advertising module, a data acquisition module, a login module, and an online payment service module. It can be used by game partners to integrate into their own applications according to their needs.

• Advertising Get access to nine mainstream online advertising platforms including AdColony, Admob, AppLovin, Facebook, UnityAd, Vungle, Mopub, Ironsource Fyber with interstitial and rewarded video Ad available.
• Data collection Provides the ability to collect user behavior data, which can be used by merchants to customize the collection and reporting of events and provide services for data refinement operations.
• Login Get access to a set of light and compact login feature
• Online payment Online payment is available among India, Indonesia, the Philippines, and other countries. Payment methods include e-wallets, debit cards, credit cards, online banking, telephone payment, and offline outlets.

Our game parnters are able to get the key info below from SHAREit AM

AppID is still required if the ad is not used

The scene and subPortal in the table will be used in Interstitial and Rewarded Ad
The scenes need to be included in Interstitial Ad
Used interface：isInterstitialAdReady()

The scene and subPortal in the table will be used in Rewarded Ad
Used interface：isRewardedAdReady /showRewardedBadgeView() The Ad space scene Sample：（scene and subPortal is the real scene in the game）

• minSdkVersion 16 or later
• compileSdkVersion 26 or later

need to upgrdge androidx, for reference:Official upgrade document

1. Add shareit_sdk.gradle into the root directory of the main module and introduce dependencies in build.gradle: the wrapped code between SHAREit start and SHAREit end

 // must be applied after your artifact generating plugin (eg. java / com.android.library/ com.android.application)
   apply from: "shareit_sdk.gradle"

2. Add default ad profile Copy the default_layer[Get the necessary setup info] file to the Android assets file under the target project, and the path is as follows

Replace the "Ad AppId" in 2.1 with "YOUR_APP_ID" in the example below

<manifest>
    <application>
         <meta-data android:name="com.ushareit.ads.KEY_APP_ID"
             android:value="YOUR_APP_ID"/>
    </application>
</manifest> 

YOUR_APP_ID is a necessary parameter. If it is not configured, the Crash prompt will be thrown in test mode; initialization will fail and ads cannot be obtained

Steps to configure Initialization are as followes:

<!-- App channel -->
<meta-data
android:name="com.sunit.channel"
android:value="SHAREit" />

<!--  'debug' is equal to test mode -->
<meta-data
android:name="com.sunit.mode"
android:value="debug" />

<!--  If the application has only one Activity , there is no need to add the string below . If there are multiple activities , the main Activity path will be added into the value part -->
<meta-data
android:name="com.sunit.mainActivity"
android:value="com.unityplayer.UnityActivity" />

<!-- If the application has only one Progress , there is no need to add the string below. If there are multiple processes in the Application, you need to declare the name of the ad-supported processes-->
<meta-data
android:name="com.sunit.adProcess"
android:value="processName" />

Provide proguard configuration by consumer-proguard-files, no need to modify the obfuscated file.

If the Aggregation SDK is introduced in the Library Module, please avoid the module's secondary confusion on the SDK.

• Admob integration Steps to configure the meta-data in the Manifest file are shown below if you need to integrate Admob.

<meta-data
 android:name="com.google.android.gms.ads.APPLICATION_ID"
 android:value="ADMOB_APP_ID" />

***ADMOBAPPID will be provided by the SHAREit ***

Steps to configure the meta-data in the Manifest file are shown below if you need to integrate Flurry.

<meta-data
  android:name="flurry.sdk.API_KEY"
  android:value="FLURRY_API_KEY" />  

FLURRY_API_KEY provided by the SHAREit service docker

1. We strongly recommend to add WRITE_EXTERNAL_STORAGE permission, and it must be copied as follows. (This permission is conducive to increasing advertising revenue!!!)

<uses-permission      
    android:name="android.permission.WRITE_EXTERNAL_STORAGE"
    tools:remove="android:maxSdkVersion"/>

2. You should request sd card permission during the first Activity#onCreate (The method contains id initialization function, you must use it)
   

   SHAREitAggregation.requestStoragePermissions();

Before version 1.5.1.0, you can use the following method

   if (ContextCompat.checkSelfPermission(this, Manifest.permission.READ_EXTERNAL_STORAGE)
           != PackageManager.PERMISSION_GRANTED || ContextCompat.checkSelfPermission(this,
                Manifest.permission.WRITE_EXTERNAL_STORAGE) != PackageManager.PERMISSION_GRANTED) {
       // Permission is not granted
       ActivityCompat.requestPermissions(this,
               new String[]{Manifest.permission.READ_EXTERNAL_STORAGE, Manifest.permission.WRITE_EXTERNAL_STORAGE},
               0);
   }

If your app use the android:targetSdkVersion="29"，Please set the value of requestLegacyExternalStorage to true in the AndroidManifest.xml：

  <manifest ... >
      <!-- This attribute is "false" by default on apps targeting
           Android 10 or higher. -->
      <application android:requestLegacyExternalStorage="true" ... >
        ...
      </application>
    </manifest>

Add account_type, content_authority under applicationId in build.gradle

    defaultConfig {
        applicationId  “com.xx.xx”
        //SHAREit begin
        resValue "string", "account_type", "${applicationId}.type"
        resValue "string","content_authority","${applicationId}.provider"
        multiDexEnabled true
        //SHAREit end
    }

to solve bug: java.lang.NoClassDefFoundError com.ushareit.aggregationsdk.InitializeProvider

a. create a file called multidex-config.pro at the level of app, the contents of the file are as follows:

-keep public class * extends android.content.ContentProvider

b. declare as follow in the file of build.gradle at the level of app, reference

android {
    buildTypes {
        release {
            multiDexKeepProguard file('multidex-config.pro')
            ...
        }
    }
}

The game level is reported at the beginning, level indicates the current level.

SHAREitAggregation.gameLevelStart(String level);

After the player dies, the level restarts and the level start event is reported again. If the game does not have a level concept, similar to a game or a game, the event must be reported at the beginning of the game. At this time, the parameter level uses -1, such as:

SHAREitAggregation.gameLevelStart(“-1”);

Reported at the end of the game level, level indicates the current level.

SHAREitAggregation.gameLevelEnd(String level);

If the player actively exits the game by pressing the return key during the game or the player dies, it is also considered as the end of the level and a level end event needs to be reported. If the game does not have a level concept, similar to a game or a game, this event should also be reported when the game ends. Parameter level uses -1, such as:

SHAREitAggregation.gameLevelEnd(“-1”);

The general data reporting is reported through the interface onEvent. The interface specific parameters are as follows

void onEvent(final Context context, final String eventId, final HashMap<String, String> params) 
// Parameter description:
context : Context object
eventId : report event name (add event name, need to notify SHAREit operation)
params : report event parameters (The parameter key name must be lowercase)
SHAREitAggregation.onEvent (context, eventId, params);

The unitID in the following parameters corresponds to the "Unit Space ID" generated by each advertising source and can be obtained in conjunction with the SHAREit service docker

1. loadAd()

InterstitialAd.loadAd(String unitId);

2. isAdReady()

This interface must be called in the main thread

//scene: Ad display scene
InterstitialAd.isAdReady(String unitId, String scene)

Special scene：If target of using isAdReady() repetitively is to access the cache instead of showAd()， the scene must use “loop” in order to avoid unneccessary data

InterstitialAd.isAdReady(unitId, ShareItAd.LOOP);

scene needs to be passed in for data analysis

3. showAd()

This interface must be called in the main thread

SDK will locate the existing cached object according to the unitId and impression will fail If there is no cached object（Need to be used with isInterstitialAdReady at the same time）

InterstitialAd.showAd(String unitId, IAdShowListener adShowListener)

SDK will find cached ad object by unitId,and it will show fail when no cached object（use with isAdReady(unitId, scene) function) For example:

//load        
InterstitialAd.loadAd(unitId);

//show
if (InterstitialAd.isAdReady(unitId, scene)) {
    InterstitialAd.showAd(unitId, null);
}

1. loadAd()

RewardedAd.loadAd(String unitId);

2. isAdReady()

This interface must be called in the main thread

RewardedAd.isAdReady(String unitId, String scene, String subPortal)

Special scene：If target of using isAdReady() repetitively is to access the cache instead of showAd()， the scene must use “loop” and the subPortal is "null" in order to avoid unneccessary data

RewardedAd.isAdReady(unitId, ShareItAd.LOOP);

scenePortal needs to be passed in for data analysis

3.showAd

This interface must be called in the main thread

There are two modles：

• SDK Managing the AD cache(Recommended)（Nee use with isAdReady(使用)，and the loadAd method without adLoadListener）
  

RewardedAd.showAd(String unitId, IAdShowListener adShowListener)

Sample：

//load        
RewardedAd.loadAd(unitId,null);

//show
if (RewardedAd.isAdReady(unitId,scene, subPortal)) {
    RewardedAd.showAd(unitId, null);
}

• Managing the AD cache yourselr（The loadAd() with adLoadListener）
  

RewardedAd.showAd(AdWrapper adWrapper, IAdShowListener adShowListener)

Sample:

RewardedAd.loadAd(unitId, new IAdLoadListener() {
    @Override
    public void onAdLoaded(String unitId, AdWrapper adWrapper) {
        RewardedAd.showAd(adWrapper, null);
    }

    @Override
    public void onAdError(String unitId, AdException adError) {

    }
});

4. showRewardedBadgeView （This method call may be more frequent, please be patient to access)

This interface must be called in the main thread

RewardedAd.showRewardedBadgeView(scene, String... subPortal);

• Method Purpose: To count the ratio of clickable ad subPortals from display to the click of the portal be helpful for funnel analysis of each rewarded video portal click performance
• Involved scenes: all rewarded video portal-related scenes
• Call timing: when The Rewarded button is from being invisible to visible, please reports all visible and clickable subPortal in the current scene

Android Sample code：Activity、Fragment or Dialog onResume()

@Override
protected void onResume() {
    super.onResume();
    if(clickable&&visible) {
    RewardedAd.showRewardedBadgeView(ShareItAd.HOME, "portal1", "portal2");
    }
}

cocos Sample code：

cc.game.on(cc.game.EVENT_SHOW, function () {
   if(clickable&&visible) {
   xx.showReWardedBadgeView(ShareItAd.HOME, "portal1", "portal2");
   }
});

SDK Managing the AD cache Modle

InterstitialAd.loadAd(String unitId);
RewardedAd.loadAd(String unitId);

Interstitial Sample：

if (InterstitialAd.isAdReady(unitId,"home")){
    InterstitialAd.showAd(unitId,null);
} else {
    InterstitialAd.loadAd(unitId);
}

Rewarded Sample：

if (RewardedAd.isAdReady(unitId,"home","portal1")){
    RewardedAd.showAd(unitId,null);
} else {
    RewardedAd.loadAd(unitId);
}

1. showBanner()

// showBanner() could enable the request and display of Banner ad and support automatic refresh.
BannerAd.showBanner(String unitId , int gravity);//gravity : Gravity.TOP  Gravity.Buttom
BannerAd.showBanner(String unitId , Activity activity , int gravity);
BannerAd.showBanner(String unitId , ViewGroup container);

2. hiddenBannerAd()

// hiddenBannerAd could hide the ads and stop auto refresh
BannerAd.hiddenBannerAd();

Please check more details with https://docs.shareitpay.in/#/12?page_id=81&si=1&lang=en

SUnit Demo

1. For security reasons, the payment key must be stored on the server, not the client
2. If you do not need to integrate Admob or AppLovin, please comment out the corresponding dependent libraries
3. If the code below is embeded in "build.gradle" under SUnit SDK

implementation fileTree(dir: 'libs', include: ['*.aar', '*.jar'])

GameLoginHelper.getInstance().isLogin();

Return value: true: logged in false: not logged in

SHAREitAggregation.userLogin(context, gameSecret, new 
    GameLoginHelper.OnLoginCompleteListener() {
    @Override
    public void onLoginSuccess(String userid，String username, String avatarUrl) {
    }
});

Parameter description： gameSecret： Reference: 2.1 Required account application SHAREitSDK.LoginListener ：Login callback class onLoginSuccess： Login success Will call back

GameLoginHelper.getInstance().getUserId()
//returns userId if successfully logged in ; otherwise returns null.

GameLoginHelper.getInstance().logout();

Return value： true：logout successful； false：logout failed

2020-08-31

BugFix:

• fix bug

Use 2.1.2.1

2020-08-11

FEATURE:

• Add Video promotion module, CP invoke the video show interface at the right time by yourself.
• Add cloud config interface for external supply which can be invoked to fetch cloud config values related. Our operators provide the key-value of the cloud config.
• Optimize code

2020-07-28

FEATURE:

• Upgrade version for Payment sdk.
• Optimize advertising loading model, and improve the efficiency of advertising loading.

CHANGES: 1.Need attention NoClassDefFoundError com.ushareit.aggregationsdk.InitializeProvider

2020-06-19

FEATURE:

• Upgrade version for Payment sdk.
• Upgrade to V5.9.0 for Facebook Audience Network

CHANGES:

1. Use the newest config file shareit_sdk.gradle
2. Add param of pass or not for gameLevelEnd event

2020-6-4

No special steps are required to upgrade to 1.6.2.1

2020-05-12

1. You should request sd card permission during the first Activity#onCreate (The method contains id initialization function, you must use it)
   • Android：SHAREitAggregation.requestStoragePermissions();
   • Unity：SHAREitSDK.SHAREitSDK.requestStoragePermissions();
2. Use the latest shareit_sdk.gradle File:
3. Add account_type, content_authority under applicationId in build.gradle

    defaultConfig {
        applicationId  “com.xx.xx”
        //SHAREit begin
        resValue "string", "account_type", "${applicationId}.type"
        resValue "string", "content_authority", "${applicationId}.provider"
        multiDexEnabled true
        //SHAREit end
    }

2020-04-20

1. Update to androidx
2. Update Ads source: admob facebook mopub applovin unityAds
3. Add admob medaitionn applovin and admob medaition unityAds

Use the latest shareit_sdk.gradle File:

1. Change the Ads source version

    ext {
        VERSION_SUNIT = "1.3.1.1"

        VERSIOVERSION_ADCOLONY_AD="4.1.0"
        VERSION_ADMOB_AD = "18.3.0"
        VERSION_ADMOB_M_FB = "5.6.1.0"
        VERSION_ADMOB_M_MOPUB = "5.10.0.0"
        VERSION_ADMOB_M_UNITYADS = "3.4.2.0"
        VERSION_ADMOB_M_APPLOVIN = "9.11.4.0"

        VERSION_APPLOVIN_AD = "9.11.4"
        VERSION_FACEBOOK_AD = "5.6.1"
        VERSION_FYBER_AD = "7.3.4"
        VERSION_IRONSOURCE_AD = "6.10.2"
        VERSION_UNITY_ADS_AD = "3.4.2"
        VERSION_VUNGLE_AD = "6.4.11"
        VERSION_MOPUB_AD = "5.10.0"
        VERSION_MOPUB_M_ADMOB = "18.3.0.3"
        VERSION_MOPUB_M_FB = "5.6.1.0"

        VERSION_PLAY_SERVICES_LOCATION = "16.0.0"
        VERSION_GSON = "2.8.1"
        VERSION_OKHTTP3 = "3.10.0"
        VERSION_FLURRY = "12.1.0"
    }

2. Add admob mediation adapter

    implementation "com.google.ads.mediation:facebook:$VERSION_ADMOB_M_FB"
    implementation("com.google.ads.mediation:mopub:$VERSION_ADMOB_M_MOPUB") {
        exclude group: 'com.mopub'
    }
    implementation "com.google.ads.mediation:unity:$VERSION_ADMOB_M_UNITYADS"
    implementation "com.google.ads.mediation:applovin:$VERSION_ADMOB_M_APPLOVIN"
    implementation "com.mopub.mediation:admob:$VERSION_MOPUB_M_ADMOB"
    implementation "com.mopub.mediation:facebookaudiencenetwork:$VERSION_MOPUB_M_FB"

2020-03-29

1. Fix bugs of reporting

2020-03-20 No special steps are required to upgrade to 1.2.5

2020-03-11

1. Update pay module, fix bugs
2. Fix Applovin Banner request API
3. Optimize Banner ad logic
4. Add floating ball function

2020-03-03

No special steps are required to upgrade to 1.2.3.6

2020-02-17

1. Optimize consumer proguard file

2020-02-14

1. No special steps are required to upgrade to 1.2.1.2

2020-02-12

1. Unified SDK version number

2020-02-11

1. SDK use maven
2. Fix bugs

2020-01-19

1. Optimize isInterstitialAdReady() of Interstitial
2. Optimize isRewardedAdReady() of Rewarded
3. Optimize showRewardedBadgeView()

2020-02-11

No special steps are required to upgrade to 1.1.1.3.

2020-01-13

No special steps are required to upgrade to 1.1.1.1.

2020-01-08

No special steps are required to upgrade to 1.1.0.1.

2020-01-07

1. 2.1 Embedded Advertising Configuration
2. 3.2.4 Adding a Default Ad configuration file
3. Deleted automatic permission request method in 6.3 and provided permission application method in 3.8

2019-12-31

1. 3.5 : modify the initialization
2. 4.1: removes the gameStart and gameEnd event reporting
3. 6.3: add automatic permission request methods

2019-12-23

1. 3.3 SDK Network Dependence of Advertising Sources (Mopub)
2. 4.3.4 more details with banner

2019-11-04

1. Interface parameter description
2. Issues with read and write permissions

2019-10-22

1. AppID must be applied
2. Login with horizontal screen adaptation
3. More detaiks for isAdReady
4. More detaiks for showAd
5. Fix bug

2019-09-10

1. Initial document

1. If you're in China, you should open VPN to test Advertising as Ads are all foreign network in our SDK.

2. If ad don't show with former unitId,you can try: Using KEY_APP_ID and corresponding unitId in our SUnitDemo to test. remember to change to former ID after test。

3. For safety reasons if integrating with payment module sdk , payment key must be stored in server and not in client.

4. If you need not someone ad network, you can exclude it in gradle file.

for example: exclude vungle network

api ("com.sunit:aggregation-android:$VERSION_SUNIT") {
        exclude group: 'com.vungle'
    }

1. check if “flurry.sdk.API_KEY” is set correctly in manifest.xml

2. check if “com.ushareit.ads.KEY_APP_ID” is set correctly in manifest.xml

3. check if “com.google.android.gms.ads.APPLICATION_ID” is set correctly in manifest.xml

4. check if “flurry.sdk.API_KEY” is set correctly in manifest.xml

5. check if “com.sunit.channel” is set SHAREit in meta-data of manifest.xml

6. check if you have removed "com.sunit.mode" in meta-data before build a release apk, you should remove it in release apk.

check if default_layer exist under assets folder provided by SHAREit operator.

See the document for details at: articles 8 and 9

1.Interstitial Ad：check if invoke InterstitialAd follow the best tips

See the document for details: Reference

if (InterstitialAd.isAdReady(unitId,"home")){
    InterstitialAd.showAd(unitId,null);
} else {
    InterstitialAd.loadAd(unitId);
}

Unity environment sample :(you must invoke isInterstitialAdReady before showInterstitialAd)

if (shareitSDK.isInterstitialAdReady(unitId,"home")){
    shareitSDK.showInterstitialAd(unitId,null);
} else {
    shareitSDK.loadInterstitialAd(unitId);
}

2. Rewarded Ad：check if invoke InterstitialAd follow the best tips

See the document for details: Reference

if (RewardedAd.isAdReady(unitId,"home","portal1")){
  RewardedAd.showAd(unitId,null); 
} else {
  RewardedAd.loadAd(unitId);
}

Unity environment sample :(you must invoke isRewardedAdReady before showRewardedAd)

if (shareitSDK.isRewardedAdReady(unitId,"home","portal1")){
shareitSDK.showRewardedAd(unitId,null);
} else {
shareitSDK.loadRewardedAd(unitId);
}

a. check if invoke gameLevelStart at the beginning of every level and pass the correct level（pass “-1” if you don't have a level concept）

b. check if invoke gameLevelEnd at the end of every level and pass the correct level（pass “-1” if you don't have a level concept）

c. check if invoke gameLevelEnd when the player dies, before the level restarts and user exits current game level.

d. check if invoke gameLevelStart when user restarts current level.

check upload for showRewardedBadgeView

a. to ensure passed scene and subPortal.

b. to ensure scene and subPortal are equal with scene and subPortal when invoked isAdReady function.

c. to ensure whether the call timing is correct (enter the scene or return to the scene again, and the rewarded video port button can be clicked, call showRewardedBadgeView method and pass in the correct scene and subPortal).

d. (special scenario) if the business needs to call isAdReady method to detect the advertisement cache, which is used to switch the button or icon status, the scene is specified as "loop", and the subPortal does not need to pass.

See the document for details: Reference

See the document for details: Reference