Menu

Android SDK documentation

I. Installation
Download the jar file

Download the jar file using this link : http://d3mljzresf650e.cloudfront.net/sdk/Playbasis+Android+SDK+for+Android+Studio.zip

Using jar file

For install Playbasis android sdk, download the playbasis jar file and its dependencies.

Under your project, create a “lib” folder and past libconceal directories. Then, under the “libs” directory, add the following package:

  • playbasis.jar
  • gson-2.3.jar
  • libconceal.jar
  • conceal_android.jar
  • conceal_so_files.jar

Your project architecture should look like this:

If you're using gradle, add the libs folder to your dependencies

dependencies {
    compile fileTree(dir: 'libs', include: ['*.jar'])
}

You can now use playbasis sdk.

Under eclipse

Download the SDK for Eclipse using this link: http://d3mljzresf650e.cloudfront.net/sdk/Playbasis+Android+SDK+for+Eclipse.zip

Under eclipse, copy armeabi, armeabi-v7a and x86 folder directly under the libs/ folder.

Do not copy conceal_so_files.jar.

Open the preferences (windows->preferences) and go on android->build. Then unchecked “Force error when external jars contain native libraries”. Due to a bug on some ADT versions, unchecked “Automatically refresh Resources and Assets folder on build”

Using AAR

Android studio provide a new way to include libraries, the AAR package. First add the playbasis.aar file into the libs directory.

Then add the require compile options into gradle configuration:

repositories {
    flatDir {
        dirs 'libs'
    }
}
dependencies {
    compile fileTree(dir: 'libs', include: ['*.jar'])
    compile(name:'playbasis', ext:'aar')
}

You can now use playbasis sdk.

II. Initialization

Your application must have a reference to the Playbasis object in order to make any API calls to the Playbasis services. Instantiate Playbasis object as static attribute on the Application class is a good way to access it everywhere from your application. Use the Playbasis.builder for instantiate your object.

public class MyApplication extends Application {
    public static Playbasis playbasis;
   
    @Override
    public void onCreate() {
        super.onCreate();
        playbasis = new Playbasis.Builder(this) //Create the builder
                .setApiKey("123456789") // Set api key
                .setApiSecret("qwertyuiop123") // Set Api secret
                .build(); // Build  
    }
}

Add Your application on the manifest file:

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
    package="com.playbasis.android.sample" >
    <uses-permission android:name="android.permission.INTERNET" />
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" />
    <application
        android:name=".MyApplication"
        android:allowBackup="true"
        android:icon="@mipmap/ic_launcher"
        android:label="@string/app_name"
        android:theme="@style/AppTheme" >
    </application>
</manifest>

Your manifest also need the INTERNET permission and the ACCESS_NETWORK_STATE permission:

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

you can alternatively add the apiKey and the apiSecret directly on the manifest file.

Under <Application> add these meta-data:

<meta-data
            android:name="com.playbasis.android.playbasissdk.apikey"
            android:value="\ 3416989394" />    
        <meta-data
            android:name="com.playbasis.android.playbasissdk.secret"
            android:value="\ qwertyuiop123" />

You can remove these keys from your builder:

public class MyApplication extends Application {
    public static Playbasis playbasis;
   
    @Override
    public void onCreate() {
        super.onCreate();
        playbasis = new Playbasis.Builder(this) //Create the builder
                .build(); // Build  
    }
}

For Display native SDK views when you're updating a player, or sending email / sms to an other player, your activity should extend FragmentActivity, and register your current view into Playbasis object:

public class MyActivity extends FragmentActivity {
    @Override
    protected void onResume() {
        super.onResume();
        MyApplication.playbasis.setActivity(this); //Register the activity to Playbasis object
    }
    @Override
    protected void onPause() {
        super.onPause();
        MyApplication.playbasis.removeActivity(); // Unregister the activity to Playbasis object
    }
III. Make a low level request

Playbasis android sdk give to the developer a bunch of single API end-point that interact with Playbasis platform. This is due to a design that the SDK provides to give developers flexibility in integrating the SDK with their own application.

You can try manually the requests at this address: http://doc.playbasis.com/pbapp/.

Request Anatomy:

All low level request follow the same structure on the SDK.

GroupNameAPI.apiName(playbasis, playerId, RequestOptions, OnResult<Object>);
GroupNameAPI: Class contend the list of method. The class name is the group method name find on the API explorer ended by “API”. You never have to instantiate this class because all his methods are static.
apiName: Static method name used for process the request.
playbasis: Playbasis object create on the section II.
playerId: Player id String. This parameter is not use on every request.
RequestOptions: Others parameters of the request. Refers to the method documentation to have more details about them.
OnResult<Object>: Interface called by the method for deliver result. This interface contain two methods “onSuccess(Object result)” called if the result success with the result object, and “onError(HttpError error)” called when an error occur (See next section for more details).

For example for get the public player info you can use:

PlayerApi.playerInfo(MyApplication.playbasis, "gregtestuser", new OnResult<Player>() {
    @Override
    public void onSuccess(Player result) {
    }
    @Override
    public void onError(HttpError error) {
    }
});

Some request need an isAsync boolean parameter. If it's set at true, the request is make on asynchronous mode, and doesn't provide any result. The onSuccess method will be called with null value. If your request doesn't have an isAsync boolean, the request is send on synchronous mode.

PlayerApi.login(MyApplication .playbasis, true, "exampleplayer", new OnResult<Boolean>() {
    @Override
    public void onSuccess(Boolean success) {
                        //success = NULL
    }
    @Override
    public void onError(HttpError error) {
    }
});

On this example, isAsync is set at true, so the request is on asynchronous mode. The success parameter will return null. On this case you can set the callback listener at null.

By the way, you can use this method without isAsync and the request will be send on synchronous mode by default.

PlayerApi.login(MyApplication .playbasis, "exampleplayer", new OnResult() {
    @Override
    public void onSuccess(Boolean success) {
        //success = true
    }
    @Override
    public void onError(HttpError error) {
    }
});

The full list of API class is:

  • - AuthApi
  • - BadgeApi
  • - CommunicationApi
  • - EngineApi
  • - GoodsApi
  • - PlayerApi
  • - QuestApi
  • - QuizApi
  • - RedeemApi
  • - ServiceApi
Error Result:

When an error happen, the onError method from OnResult interface is called. HttpError can be three kind of error:

- Exception (extended class): standard Java exception. HttpError extend this class

- NetworkResponse: Network error class. Contain headers and data returned by a standard HTTP request when the status code is not 200.

- RequestError: Error name and code returned by the Playbasis API.

NetworkResponse can be accessed by using:

@Override
            public void onError(HttpError error) {
               error.networkResponse; // access the the  NetworkResponse attribute
                                error.networkResponse.statusCode; // get the http status code (int)
                                error.networkResponse.data; // get the http errors data (byte[])
            }

RequestError can be accessed by using:

@Override
            public void onError(HttpError error) {
               error.requestError; // access the the  RequestError attribute
                                error.requestError.message; // get the server request message(String)
                                error.requestError.errorCode; // get the server request error code (int)
            }

The full description of possible errorCode is returned by the backend can be found on RequestError.ERROR_CODE interface.

IV. Send actions (Hight level request)

The SDK simplify the way to send events to the dashboard by given a bunch of standard actions.

Engine rule request can be send in two way, synchronously, or asynchronously. These two way are pretty the same; however, async call is for developers who only wan to track their player's actions. On the other way, sync method give a feedback from this action using the OnResult interface.

When the device doesn't have any network connection, the request is saved locally on an encrypt file, and it will be send later when the device will recover an Internet connection. By this wait you can keep using these method when the player is in off-line mode without loosing data.

Sync

For send a synchronous request, simply call the Do() method on the Playbasis object. Opposite to low level request, Do() is not a static method. Playbasis object have to been instantiate before with the Playbasis.Builder (see part II).

Thee parameters are mandatory for make a Do request:

playerId: (String) player id as used in client's website
rule: (String) name of action performed
OnResult<Rule> interface: Standard interface for callback.

Others parameters can be added on a Do() method:

url: (String) URL of the page that trigger the action or any identifier string - Used for logging, URL specific rules, and rules that trigger only when a specific identifier string is supplied
reward: (String) name of the point-based reward to give to player, if the action trigger custom-point reward that doesn't specify reward name
quantity: (String) amount of the point-based reward to give to player, if the action trigger custom-point reward that doesn't specify reward quantity
MyApplication.playbasis.Do("exampleplayer", "click", new OnResult<Rule>() {
            @Override
            public void onSuccess(Rule result) {
            }
            @Override
            public void onError(HttpError error) {
            }
        });
Async

For send an asynchronous request, simply call the Track() method on the Playbasis object. Like Do() method, Track() is not static, Playbasis object have to be instantiate. Track() is almost the same than Do(), except this method doesn't have callback.

Two parameters are mandatory for a Do request:

playerId: (String) player id as used in client's website
rule: (String) name of action performed

Others parameters can be added to the Do() method:

url: (String) URL of the page that trigger the action or any identifier string
- Used for logging, URL specific rules, and rules that trigger only when a specific identifier string is supplied
reward: (String) name of the point-based reward to give to player, if the action trigger custom-point reward that doesn't specify reward name
quantity: (String) amount of the point-based reward to give to player, if the action trigger custom-point reward that doesn't specify reward quantity
MyApplication.playbasis.Track("exampleplayer", "click");
Rule event

The RuleAction enum contain a list of standard rule provided by playbasis dashboard. On Do() or Track(), you can replace the rule parameter by a RuleAction value.

MyApplication.playbasis.Track("exampleplayer", RuleAction.CLICK);

The values contained on RuleAction enum is:

  • BUY
  • CHECKIN
  • CLICK
  • COMMENT
  • COMPARE
  • FBCOMMENT
  • FBLIKE
  • FBPOST
  • FBSTATUS
  • LIKE
  • LOGIN
  • LOGOUT
  • LOVE
  • ORDER
  • PAYMENT
  • READ
  • REDEEM
  • REGISTER
  • REVIEW
  • SHARE
  • TWEET
  • VISIT
  • WANT
  • WATCH

For more details, see the RuleEvent javadoc.

UI event

Like RuleAction, the UIEvent enum contain the list of standard android events provided by the dashboard.

MyApplication.playbasis.Track("exampleplayer", UIEvent.LONG_CLICK);

The values contained on UIEvent is:

  • CLICK
  • LONG_CLICK
  • FOCUS_CHANGE
  • TOUCH
  • KEY
  • MENU_ITEM
  • VIEW_CREATE
  • VIEW_DISPLAY
  • VIEW_REMOVE
  • VIEW_DESTROY

For more details, see the UIEvent javadoc.

Custom

You can use Do() and Track() with custom actions. First you need to create the action on the dashboard:

Select the action dashboard and click on insert.

Create a new action. “Action Name” is on lower case only. When your action is create, go on “engine” dashboard and create a new rule.

Click on “Add action” button and select your custom action. Click on save and it's done, your rule is added.

If you want to send a request to this rule, simply make a Do() or Track() call, and put your action name on the rule parameter as a string:

MyApplication.playbasis.Track("exampleplayer", “mycustomaction”);
V. Token.

A token is used by some requests for post data on the dashboard. For request a token, call the getAuthToken() method from the Authenticator object into the playbasis class.

MyApplication.playbasis.getAuthenticator().getAuthToken(new OnResult<AuthToken>() {
    @Override
    public void onSuccess(AuthToken result) {
    }
    @Override
    public void onError(HttpError error) {
    }
});

A good practice is to call the method just after the playbasis instantiation:

playbasis = new Playbasis.Builder(this)
        .setBackendUrl("https://api-sandbox.pbapp.net/")
        .setApiKey("3416989394")
        .setApiSecret("b1fa1529410702557a6fe2f3913768a0")
        .build();
playbasis.getAuthenticator().getAuthToken();

Note: getAuthToken can be called without parameter

This method request the current token from the backend and save it securely into the device. If a token was previously saved it will be returned without process the API.

The token expire after 3 days. Playbasis SDK will automatically regenerate it on the case. By the way, the token have to been initialize first.