SDK Android

From Radarus Project Wiki
Jump to: navigation, search

Contents

Overview

Android SDK provides your application with all functionality of RADARUS. Before you start, you have to register your application on developer portal to obtain application id.

Integration

To integrate RADARUS API, you have to add sources of SDK to your application.

Core API concepts

RHost object

Access to RADARUS API is provided by the instance of the RHost class.


Response object

Most of operations are asynchronous, so actual data is delivered via callbacks. All callbacks receive single parameter: Response object. Type of Responce object is defined by corresponding request.

All response objects are inherited from ApiRequest.BaseResponse class. Here is a list of ApiRequest.BaseResponse class methods:

  • boolean hadError () : returns true if error occurred, false - otherwise
  • ErrorInfo getErrorInfo () : returns object containing detailed information about error, or null if request was processed successfully

Also, most of the Response objects have getDataEntry method which provides access to the response data. Result type of getDataEntry method depends on request.

Basic API

Initialization

To initialize RADARUS API you need:

Create an instance of RHost object

public static final int APP_ID = 100;
 
RHost rHost = new RHost(getApplicationContext(),APP_ID);

Notify API when top activity of your application changes

Add Rhost.setActivity calls to onResume and onPause methods of your application's activities:

@Override
public void onResume ()
 {
  rHost.setActivity(this);
 
  super.onResume();
 }
 
@Override
public void onPause ()
 {
  rHost.setActivity(null);
 
  super.onPause();
 }

Login

public class AppCore
 {
  ...
  public Cancelable markUserLoginAsExtUser (String userExtLogin, String userName, ApiRequestLogin.Callback callback);
  public Cancelable markUserLoginAsExtUser (String userExtLogin, String userName, ApiRequestLogin.Callback callback, ApiOptions options);
  ...
 }

Synopsis:

Login external (application) user into RADARUS. If there is no such user, the new user account will be created by RADARUS automatically. If there exists RADARUS user session, it will be logged out automatically.

Parameters:

userExtLogin : User login (unique user identifier in your system)
userName : User name
callback : callback which will be called once operation completed
options : operation options (optional)

Response data (ApiRequestLogin.DataEntry):

long getUserId() : RADARUS system user id assigned to this external user

Also current user id can be retrieved using AppCore.getCurrentUserId() call. This method returns userId for currently logged in user, or AppCore.USER_ID_UNDEFINED otherwise. This method can be used to check if user is logged in in RADARUS.

Code example:

rHost.getAppCore().markUserLoginAsExtUser
 ("some_external_user_id",
  "John Doe",
  new ApiRequestLogin.Callback()
   {
    public void onResponseReceived (ApiRequestLogin.Response response)
     {
      if (!response.hadError())
       {
        System.out.println("login succeeded for user : " + response.getDataEntry().getUserId());
       }
      else
       {
        System.out.println("login error: " + response.getErrorInfo().getErrorMessage());
       }
      }
    });


UI Dashboard

UIDashboard class provides methods to control dashboard visibility and check dashboard visibility status:

public class UIDashboard
 {
  ...
  public void show ();
  public void hide ();
  public boolean isVisible ();
  ...
 }

Code example:

// show dashboard
rHost.getUIDashboard().show();
 
// hide dashboard
rHost.getUIDashboard().hide();
 
// check if dashboard is visible
if (rHost.getUIDashboard().isVisible())
 {
  // dashboard is visible
 }

Extended API

Groups

When user joins or leaves group you may notify Radarus by using markUserExtGroupJoin and markUserExtGroupLeave methods of AppCore class:

public class AppCore
 {
  ...
  public Cancelable markUserExtGroupJoin (long extGroupId, ApiRequestActionSimple.Callback callback, ApiOptions options);
  public Cancelable markUserExtGroupJoin (long extGroupId, ApiRequestActionSimple.Callback callback);
 
  public Cancelable markUserExtGroupLeave (long extGroupId, ApiRequestActionSimple.Callback callback, ApiOptions options);
  public Cancelable markUserExtGroupLeave (long extGroupId, ApiRequestActionSimple.Callback callback);
  ...
 }


Actions

public class AppAction
 {
  ...
  public Cancelable execAction (int actionId, ApiRequestActionSimple.Callback callback, ApiOptions options);
  public Cancelable execAction (int actionId, ApiRequestActionSimple.Callback callback);
 
  public Cancelable execActionOnOtherUser (int actionId, long corrUserId, ApiRequestActionSimple.Callback callback, ApiOptions options);
  public Cancelable execActionOnOtherUser (int actionId, long corrUserId, ApiRequestActionSimple.Callback callback);
 
  public Cancelable execActionOnOtherExtUser (int actionId, String corrUserExtLogin, ApiRequestActionSimple.Callback callback, ApiOptions options);
  public Cancelable execActionOnOtherExtUser (int actionId, String corrUserExtLogin, ApiRequestActionSimple.Callback callback);
 
  public Cancelable execActionOnExtGroup (int actionId, long extGroupId, ApiRequestActionSimple.Callback callback, ApiOptions options);
  public Cancelable execActionOnExtGroup (int actionId, long extGroupId, ApiRequestActionSimple.Callback callback);
  ...
 }


UI Button

UIButton class provides methods to control dashboard visibility and check Radarus button visibility status:

public class UIButton
 {
  ...
  public void show ();
  public void hide ();
  public boolean isVisible ();
  ...
 }

Code example:

// show button
rHost.getUIButton().show();
 
// hide button
rHost.getUIButton().hide();
 
// check if button is visible
if (rHost.getUIButton().isVisible())
 {
  // button is visible
 }


Logout

public class AppCore
 {
  ...
  public Cancelable markUserLogout (ApiRequestLogout.Callback callback, ApiOptions options);
  public Cancelable markUserLogout (ApiRequestLogout.Callback callback);
  ...
 }

Synopsis: Logout external (application) user from RADARUS. Actually, RADARUS will try to keep track of user session automatically, by issuing independent ping requests to server every few minutes (if there is no other activity) and it will logout user by timeout. But you may provide better experience if you call this method explicitly once user logouts from your system.

Parameters:

callback : callback function to be called once operation completed
options : operation options (optional)

Graph API

Buddies

public class AppBuddy
 {
  ...
  public static class UserInfoItem
   {
    public long getUserId (); // User's id in RADARUS
    public String getUserName (); // User's display name
    public String getUserIcon (); // User's avatar icon
    public String getUserExtLogin (); // User's external login used (if any)
    public boolean isFriend (); // true if user is a friend of requesting (currently logged in user)
    public boolean isOnline (); // true if user is online in the requesting (current) application
   }
  ...
 }


public class AppBuddy
 {
  ...
  public Cancelable reqThisUserBuddiesItemList (ApiRequestUserBuddyList.Callback callback, ApiOptions options);
  public Cancelable reqThisUserBuddiesItemList (ApiRequestUserBuddyList.Callback callback);
  ...
 }


Friends

public class AppBuddy
 {
  ...
  public Cancelable execSendFriendReq (long corrUserId, ApiRequestActionSimple.Callback callback, ApiOptions options);
  public Cancelable execSendFriendReq (long corrUserId, ApiRequestActionSimple.Callback callback);
 
  public Cancelable execSendFriendReqToExtUser (String corrUserExtLogin, ApiRequestActionSimple.Callback callback, ApiOptions options);
  public Cancelable execSendFriendReqToExtUser (String corrUserExtLogin, ApiRequestActionSimple.Callback callback);
  ...
 }


Users

public class AppCore
 {
  ...
  public static class UserInfoItem
   {
    public long getUserId (); // User's id in RADARUS
    public String getUserName (); // User's display name
    public String getUserIcon (); // User's avatar icon
    public String getUserExtLogin (); // User's external login used (if any)
    public boolean isFriend (); // true if user is a friend of requesting (currently logged in user)
    public boolean isOnline (); // true if user is online in the requesting (current) application
   }
  ...
 }


public class AppCore
 {
  ...
  public Cancelable reqAnyUserInfo (long userId, ApiRequestAnyUserInfo.Callback callback, ApiOptions options);
  public Cancelable reqAnyUserInfo (long userId, ApiRequestAnyUserInfo.Callback callback);
 
  public Cancelable reqAnyExtUserInfo (String userExtLogin, ApiRequestAnyUserInfo.Callback callback, ApiOptions options);
  public Cancelable reqAnyExtUserInfo (String userExtLogin, ApiRequestAnyUserInfo.Callback callback);
  ...
 }


Pride API

Pride API provides a functionality that allows your application users share what they have achieved in your application.

Progress

public class AppProgress
 {
  ...
  public Cancelable execPostProgress (int progressId, long progressValue, ApiRequestActionSimple.Callback callback, ApiOptions options);
  public Cancelable execPostProgress (int progressId, long progressValue, ApiRequestActionSimple.Callback callback);
  ...
 }


public class AppProgress
 {
  ...
  public static class UserInfoItem
   {
    public int getAppId (); // Application id in RADARUS
    public int getProgressId (); // Progress id registered for your application
    public int getProgressCode (); // Progress timespan code (ALL_TIME, THIS_MONTH, THIS_WEEK, etc)
    public long getUserId (); // User's id in RADARUS
    public String getUserExtLogin (); // User's external login used (if any)
    public String getUserName (); // User's display name
    public String getUserIcon (); // User's avatar icon
    public long getValue (); // Progress value
    public long getPoints (); // Synonym for value
    public long getUpdateTimestamp (); //  timestamp for last update (in ms since 1/1/1970)
    public int getRank (); // User's position in progress list
   }
  ...
 }


AppProgress.PROGRESS_CODE_* constants:

AppProgress.PROGRESS_CODE_ALL_TIME  : All time
AppProgress.PROGRESS_CODE_THIS_MONTH : For this month
AppProgress.PROGRESS_CODE_THIS_WEEK  : For this week


public class AppProgress
 {
  ...
  public Cancelable reqAllUsersItemList (int progressId, int progressCode, ApiRequestProgressUserItemList.Callback callback, ApiOptions options);
  public Cancelable reqAllUsersItemList (int progressId, int progressCode, ApiRequestProgressUserItemList.Callback callback);
 
  public Cancelable reqThisUserBuddiesItemList (int progressId, int progressCode, ApiRequestProgressUserItemList.Callback callback, ApiOptions options);
  public Cancelable reqThisUserBuddiesItemList (int progressId, int progressCode, ApiRequestProgressUserItemList.Callback callback);
 
  public Cancelable reqAnyUserItem (int progressId, int progressCode, long userId, ApiRequestProgressUserItem.Callback callback, ApiOptions options);
  public Cancelable reqAnyUserItem (int progressId, int progressCode, long userId, ApiRequestProgressUserItem.Callback callback);
 
  public Cancelable reqThisUserItem (int progressId, int progressCode, ApiRequestProgressUserItem.Callback callback, ApiOptions options);
  public Cancelable reqThisUserItem (int progressId, int progressCode, ApiRequestProgressUserItem.Callback callback);
  ...
 }


public class AppProgress
 {
  ...
  public static class AppInfoItem
   {
    public int getAppId (); // Application id in RADARUS
    public int getProgressId (); // Progress id registered for your application
    public String getProgressName (); // Progress name
    public String getProgressIcon (); // Progress icon url
    public String getProgressData (); // Application specific data (opaque for RADARUS) associated with the item via developer portal. Can be used to build data-driven custom tunable logic.
    public String getAppData (); // Synonym for getProgressData()
   }
  ...
 }


public class AppProgress
 {
  ...
  public Cancelable reqAppItemList (ApiRequestProgressAppItemList.Callback callback, ApiOptions options);
  public Cancelable reqAppItemList (ApiRequestProgressAppItemList.Callback callback);
  ...
 }

Synopsis:

Application vocabulary extraction : returns all progresses defined for the application on developer portal.


Badges

Method execUnlock of AppBadge class unlocks badge for current user:

public class AppBadge
 {
  ...
  public Cancelable execUnlock (int badgeId, ApiRequestActionSimple.Callback callback, ApiOptions options);
  public Cancelable execUnlock (int badgeId, ApiRequestActionSimple.Callback callback);
  ...
 }

Synopsis:

Unlocks application badge for current user.

Parameters:

badgeId  : badge id to unlock
callback  : callback to be called once operation completed
options  : operation options (optional)
public class AppBadge
 {
  ...
  public static class UserInfoItem
   {
    public int getAppId (); // Application id in RADARUS
    public int getBadgeId (); // Badge id (registered for your application on developer portal)
    public int getBadgeName (); // Badge name
    public String getBadgeIcon (); // Badge icon url
    public long getUserId (); // User's id in RADARUS
    public long getUnlockTimestamp (); // Timestamp for last update (in ms since 1/1/1970)
   }
  ...
 }


A list of unlocked badges can be retrieved by using reqAnyUserItemList or reqThisUserItemList methods:

public class AppBadge
 {
  ...
  public Cancelable reqAnyUserItemList (long userId, ApiRequestBadgeUserItemList.Callback callback, ApiOptions options);
  public Cancelable reqAnyUserItemList (long userId, ApiRequestBadgeUserItemList.Callback callback);
 
  public Cancelable reqThisUserItemList (ApiRequestBadgeUserItemList.Callback callback, ApiOptions options);
  public Cancelable reqThisUserItemList (ApiRequestBadgeUserItemList.Callback callback);
  ...
 }


Synopsis:

Requests a list of unlocked badges for current (reqThisUserItemList) or any other (reqAnyUserItemList) user.

Parameters:

userId  : userId of user for which list of unlocked badges is requested (is used for reqAnyUserItemList only)
callback  : callback to be called once operation completed
options  : operation options (optional)

If request succeeds, Response.getDataEntry() method returns an array of AppBadge.UserInfoItem objects which describes badges unlocked by the user.

public class AppBadge
 {
  ...
  public static class AppInfoItem
   {
    public int getAppId (); // Application id in RADARUS
    public int getBadgeId (); // Badge id (registered for your application on developer portal)
    public int getBadgeName (); // Badge name
    public String getBadgeIcon (); // Badge icon url
    public String getBadgeData (); // Application specific data (opaque for RADARUS) associated with the item via developer portal. Can be used to build data-driven custom tunable logic.
    public String getAppData (); // Synonym for badgeData
   }
  ...
 }

A list of all badges available for application can be retrieved by using reqAppItemLis method:

public class AppBadge
 {
  ...
  public Cancelable reqAppItemList (ApiRequestBadgeAppItemList.Callback callback, ApiOptions options);
  public Cancelable reqAppItemList (ApiRequestBadgeAppItemList.Callback callback);
  ...
 }

Synopsis:

Application vocabulary extraction : returns all badges defined for the application on developer portal.

Parameters:

callback  : callback to be called once operation completed
options : operation options (optional)

If request succeeds, Response.getDataEntry() method returns an array of AppBadge.AppInfoItem objects which describes all badges defined for the application on developer portal.

Personal tools
Namespaces

Variants
Actions
Navigation
Toolbox