SDK iOS

From Radarus Project Wiki
Jump to: navigation, search

Contents

Overview

iOS 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 Response object is defined by corresponding request.

All response objects are inherited from RDApiRequestBaseResponse class. Here is a list of RDApiRequestBaseResponse class methods and properties:

  • -(BOOL) hadError : method which returns YES if error occurred, NO - otherwise
  • @property RDApiRequestErrorInfo* errorInfo : property which contains detailed information about error, or nil if request was processed successfully

Also, most of the Response objects have dataEntry property which provides access to the response data. Type of dataEntry property depends on request.

Basic API

Initialization

To initialize RADARUS API you need:

Create an instance of RHost object

#define APP_ID (100)
 
RHost* rHost = [[RHost alloc] initWithAppId: APP_ID];

Login

@interface RDAppCore : NSObject {
//...
-(id<RDCancelable>) markUserLoginAsExtUserWithLogin:(NSString*) login
                                               name:(NSString*) name
                                        andCallback:(id<RDApiRequestLoginCallback>) callback;
 
-(id<RDCancelable>) markUserLoginAsExtUserWithLogin:(NSString*) login
                                               name:(NSString*) name
                                           callback:(id<RDApiRequestLoginCallback>) callback
                                         andOptions:(NSDictionary*) 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:

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

Response data (RDApiRequestLoginDataEntry):

@property (nonatomic,assign,readonly) RDUserId userId : RADARUS system user id assigned to this external user

Also current user id can be retrieved using currentUserId() property of AppCore object. This property contains userId for currently logged in user, or RDUserIdUndefined otherwise. This method can be used to check if user is logged in in RADARUS.

Code example:

-(void) loginAsExtUserWithLogin:(NSString*) login andName:(NSString*) name {
    [self.rHost.appCore markUserLoginAsExtUserWithLogin:login
                                                   name:name
                                            andCallback:self];
}
 
-(void) rdApiRequestDidReceiveLoginResponse:(RDApiRequestLoginResponse*) response
{
    if (!response.hadError) {
        NSLog(@"Login succeeded for user: %llu",dataEntry.userId);
    }
    else {
        NSLog(@"Login error: %@",dataEntry.errorInfo.errorMessage);
    }
}


UI Dashboard

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

@interface RDDashboard : NSObject
//...
+ (BOOL)isVisible;
+ (void)show;
+ (void)hide;
//...
@end

Code example:

// show dashboard
[RDDashboard show];
 
// hide dashboard
[RDDashboard hide];
 
// check if dashboard is visible
if ([RDDashboard isVisible])
 {
  // dashboard is visible
 }


Extended API

Groups

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

@interface RDAppCore : NSObject
//...
-(id<RDCancelable>) markUserExtGroupJoin:(RDExtGroupId) extGroupId
                            withCallback:(id<RDApiRequestActionSimpleCallback>) callback;
 
-(id<RDCancelable>) markUserExtGroupJoin:(RDExtGroupId) extGroupId
                            withCallback:(id<RDApiRequestActionSimpleCallback>) callback
                              andOptions:(NSDictionary*) options;
 
-(id<RDCancelable>) markUserExtGroupLeave:(RDExtGroupId) extGroupId
                             withCallback:(id<RDApiRequestActionSimpleCallback>) callback;
 
-(id<RDCancelable>) markUserExtGroupLeave:(RDExtGroupId) extGroupId
                             withCallback:(id<RDApiRequestActionSimpleCallback>) callback
                               andOptions:(NSDictionary*) options;
//...
@end

Actions

@interface RDAppAction : NSObject
//...
-(id<RDCancelable>) execAction:(int) actionId
                  withCallback:(id<RDApiRequestActionSimpleCallback>) callback
                    andOptions:(NSDictionary*) options;
 
-(id<RDCancelable>) execAction:(int) actionId
                  withCallback:(id<RDApiRequestActionSimpleCallback>) callback;
 
-(id<RDCancelable>) execAction:(int) actionId
                   onOtherUser:(RDUserId) corrUserId
                  withCallback:(id<RDApiRequestActionSimpleCallback>) callback
                    andOptions:(NSDictionary*) options;
 
-(id<RDCancelable>) execAction:(int) actionId
                   onOtherUser:(RDUserId) corrUserId
                  withCallback:(id<RDApiRequestActionSimpleCallback>) callback;
 
-(id<RDCancelable>) execAction:(int) actionId
                onOtherExtUser:(NSString*) corrUserExtLogin
                  withCallback:(id<RDApiRequestActionSimpleCallback>) callback
                    andOptions:(NSDictionary*) options;
 
-(id<RDCancelable>) execAction:(int) actionId
                onOtherExtUser:(NSString*) corrUserExtLogin
                  withCallback:(id<RDApiRequestActionSimpleCallback>) callback;
 
-(id<RDCancelable>) execAction:(int) actionId
                    onExtGroup:(RDExtGroupId) extGroupId
                  withCallback:(id<RDApiRequestActionSimpleCallback>) callback
                    andOptions:(NSDictionary*) options;
 
-(id<RDCancelable>) execAction:(int) actionId
                    onExtGroup:(RDExtGroupId) extGroupId
                  withCallback:(id<RDApiRequestActionSimpleCallback>) callback;
//...
@end


UI Button

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

@interface RDButton : NSObject
//...
+(void) show;
+(void) hide;
+(BOOL) isVisible;
//...
@end

Code example:

// show button
[RDButton show];
 
// hide button
[RDButton hide];
 
// check if button is visible
if ([RDButton isVisible])
 {
  // button is visible
 }


Logout

@interface RDAppCore : NSObject
//...
-(id<RDCancelable>) markUserLogoutWithCallback:(id<RDApiRequestActionSimpleCallback>) callback;
 
-(id<RDCancelable>) markUserLogoutWithCallback:(id<RDApiRequestActionSimpleCallback>) callback
                                    andOptions:(NSDictionary*) options;
//...
@end

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

@interface RDAppBuddyUserInfoItem : NSObject
//...
@property RDUserId  userId;       // User's id in RADARUS
@property NSString* userName;     // User's display name
@property NSString* userExtLogin; // User's external login used (if any)
@property BOOL      isFriend;     // YES if user is a friend of requesting (currently logged in user)
@property BOOL      isOnline;     // YES if user is online in the requesting (current) application
@property NSString* userIconUrl;  // User's avatar icon
//...
@end


@interface RDAppBuddy : NSObject
//...
-(id<RDCancelable>) reqThisUserBuddiesItemListWithCallback:(id<RDApiRequestUserBuddyListCallback>) callback
                                                andOptions:(NSDictionary*) options;
 
-(id<RDCancelable>) reqThisUserBuddiesItemListWithCallback:(id<RDApiRequestUserBuddyListCallback>) callback;
//...
@end


Friends

@interface RDAppBuddy : NSObject
//...
-(id<RDCancelable>) execSendFriendReq:(RDUserId) corrUserId
                         withCallback:(id<RDApiRequestActionSimpleCallback>) callback
                           andOptions:(NSDictionary*) options;
 
-(id<RDCancelable>) execSendFriendReq:(RDUserId) corrUserId
                         withCallback:(id<RDApiRequestActionSimpleCallback>) callback;
 
-(id<RDCancelable>) execSendFriendReqToExtUser:(NSString*) corrUserIdExtLogin
                                  withCallback:(id<RDApiRequestActionSimpleCallback>) callback
                                    andOptions:(NSDictionary*) options;
 
-(id<RDCancelable>) execSendFriendReqToExtUser:(NSString*) corrUserExtLogin
                                  withCallback:(id<RDApiRequestActionSimpleCallback>) callback;
//...
@end


Users

@interface RDAppCoreUserInfoItem
//...
@property RDUserId  userId;       // User's id in RADARUS
@property NSString* userName;     // User's display name
@property NSString* userExtLogin; // User's external login used (if any)
@property BOOL      isFriend;     // YES if user is a friend of requesting (currently logged in user)
@property BOOL      isOnline;     // YES if user is online in the requesting (current) application
@property NSString* userIconUrl;  // User's avatar icon
//...
@end


@interface RDAppCore
//...
-(id<RDCancelable>) reqAnyUserInfoForUserId:(RDUserId) userId
                               withCallback:(id<RDApiRequestAnyUserInfoCallback>) callback
                                 andOptions:(NSDictionary*) options;
-(id<RDCancelable>) reqAnyUserInfoForUserId:(RDUserId) userId
                               withCallback:(id<RDApiRequestAnyUserInfoCallback>) callback;
 
 
-(id<RDCancelable>) reqAnyUserInfoForUserExtLogin:(NSString*) userExtLogin
                                     withCallback:(id<RDApiRequestAnyUserInfoCallback>) callback
                                       andOptions:(NSDictionary*) options;
-(id<RDCancelable>) reqAnyUserInfoForUserExtLogin:(NSString*) userExtLogin
                                     withCallback:(id<RDApiRequestAnyUserInfoCallback>) callback;
//...
@end


Pride API

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

Progress

@interface RDAppProgress : NSObject
//...
-(id<RDCancelable>) execPostProgress:(NSUInteger) progressId
                               value:(unsigned long long) progressValue
                        withCallback:(id<RDApiRequestActionSimpleCallback>) callback
                          andOptions:(NSDictionary*) options;
 
-(id<RDCancelable>) execPostProgress:(NSUInteger) progressId
                               value:(unsigned long long) progressValue
                        withCallback:(id<RDApiRequestActionSimpleCallback>) callback;
//...
@end


@interface RDAppProgressUserInfoItem : NSObject
//...
@property NSUInteger         appId;           // Application id in RADARUS
@property NSUInteger         progressId;      // Progress id registered for your application
@property NSUInteger         progressCode;    // Progress timespan code (ALL_TIME, THIS_MONTH, THIS_WEEK, etc)
@property unsigned long long progressValue;   // Progress value
@property RDUserId           userId;          // User's id in RADARUS
@property NSString*          userName;        // User's display name
@property NSString*          userExtLogin;    // User's external login used (if any)
@property RDTimestamp        updateTimestamp; // Timestamp for last update (in ms since 1/1/1970)
@property NSUInteger         rank;            // User's position in progress list
@property NSString*          userIconUrl;     // User's avatar icon
//...
@end


RD_APP_PROGRESS_CODE_* constants:

RD_APP_PROGRESS_CODE_ALL_TIME  : All time
RD_APP_PROGRESS_CODE_THIS_MONTH : For this month
RD_APP_PROGRESS_CODE_THIS_WEEK  : For this week


@interface RDAppProgress : NSObject
//...
-(id<RDCancelable>) reqAllUsersItemList:(NSUInteger) progressId
                           progressCode:(NSUInteger) progressCode
                           withCallback:(id<RDApiRequestProgressUserItemListCallback>) callback
                             andOptions:(NSDictionary*) options;
 
-(id<RDCancelable>) reqAllUsersItemList:(NSUInteger) progressId
                           progressCode:(NSUInteger) progressCode
                           withCallback:(id<RDApiRequestProgressUserItemListCallback>) callback;
 
-(id<RDCancelable>) reqThisUserBuddiesItemList:(NSUInteger) progressId
                                  progressCode:(NSUInteger) progressCode
                                  withCallback:(id<RDApiRequestProgressUserItemListCallback>) callback
                                    andOptions:(NSDictionary*) options;
 
-(id<RDCancelable>) reqThisUserBuddiesItemList:(NSUInteger) progressId
                                  progressCode:(NSUInteger) progressCode
                                  withCallback:(id<RDApiRequestProgressUserItemListCallback>) callback;
 
-(id<RDCancelable>) reqAnyUserItem:(NSUInteger) progressId
                      progressCode:(NSUInteger) progressCode
                            userId:(RDUserId) userId
                      withCallback:(id<RDApiRequestProgressUserItemCallback>) callback
                        andOptions:(NSDictionary*) options;
 
-(id<RDCancelable>) reqAnyUserItem:(NSUInteger) progressId
                      progressCode:(NSUInteger) progressCode
                            userId:(RDUserId) userId
                      withCallback:(id<RDApiRequestProgressUserItemCallback>) callback;
 
-(id<RDCancelable>) reqThisUserItem:(NSUInteger) progressId
                       progressCode:(NSUInteger) progressCode
                       withCallback:(id<RDApiRequestProgressUserItemCallback>) callback
                         andOptions:(NSDictionary*) options;
 
-(id<RDCancelable>) reqThisUserItem:(NSUInteger) progressId
                       progressCode:(NSUInteger) progressCode
                       withCallback:(id<RDApiRequestProgressUserItemCallback>) callback;
//...
@end


@interface RDAppProgressAppInfoItem : NSObject
//...
@property NSUInteger appId;           // Application id in RADARUS
@property NSUInteger progressId;      // Progress id registered for your application
@property NSString*  progressName;    // Progress name
@property NSString*  progressData;    // Application specific data (opaque for RADARUS) associated with the item via developer portal. Can be used to build data-driven custom tunable logic.
@property NSString*  progressIconUrl; // Progress icon url
//...
@end


@interface RDAppProgress
//...
-(id<RDCancelable>) reqAppItemListWithCallback:(id<RDApiRequestProgressAppItemListCallback>) callback
                                    andOptions:(NSDictionary*) options;
 
-(id<RDCancelable>) reqAppItemListWithCallback:(id<RDApiRequestProgressAppItemListCallback>) callback;
//...
@end

Synopsis:

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


Badges

Methods execUnlock:withCallback:andOptions: and execUnlock:withCallback: of AppBadge class unlocks badge for current user:

@interface RDAppBadge : NSObject
//...
-(id<RDCancelable>) execUnlock:(NSUInteger) badgeId
                  withCallback:(id<RDApiRequestActionSimpleCallback>) callback
                    andOptions:(NSDictionary*) options;
 
-(id<RDCancelable>) execUnlock:(NSUInteger) badgeId
                  withCallback:(id<RDApiRequestActionSimpleCallback>) callback;
//...
@end

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)
@interface RDAppBadgeUserInfoItem : NSObject
//...
@property NSUInteger  appId;           // Application id in RADARUS
@property NSUInteger  badgeId;         // Badge id (registered for your application on developer portal)
@property NSString*   badgeName;       // Badge name
@property RDUserId    userId;          // User's id in RADARUS
@property RDTimestamp unlockTimestamp; // Timestamp for last update (in ms since 1/1/1970)
@property NSString*   badgeIconUrl;    // Badge icon url
//...
@end


A list of unlocked badges can be retrieved by using reqAnyUserItemList:withCallback:andOptions:, reqAnyUserItemList:withCallback:, reqThisUserItemListWithCallback:andOptions: or reqThisUserItemListWithCallback: methods:

@interface RDAppBadge : NSObject
//...
-(id<RDCancelable>) reqAnyUserItemList:(RDUserId) userId
                          withCallback:(id<RDApiRequestBadgeUserItemListCallback>) callback
                            andOptions:(NSDictionary*) options;
 
-(id<RDCancelable>) reqAnyUserItemList:(RDUserId) userId
                          withCallback:(id<RDApiRequestBadgeUserItemListCallback>) callback;
 
-(id<RDCancelable>) reqThisUserItemListWithCallback:(id<RDApiRequestBadgeUserItemListCallback>) callback
                                         andOptions:(NSDictionary*) options;
 
-(id<RDCancelable>) reqThisUserItemListWithCallback:(id<RDApiRequestBadgeUserItemListCallback>) callback;
//...
@end


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's dataEntryproperty contains an array of RDAppBadgeUserInfoItem objects which describes badges unlocked by the user.

@interface RDAppBadgeAppInfoItem : NSObject
//...
@property NSUInteger appId;        // Application id in RADARUS
@property NSUInteger badgeId;      // Badge id (registered for your application on developer portal)
@property NSString*  badgeName;    // Badge name
@property NSString*  badgeData;    // Application specific data (opaque for RADARUS) associated with the item via developer portal. Can be used to build data-driven custom tunable logic.
@property NSString*  badgeIconUrl; // Badge icon url
//...
@end

A list of all badges available for application can be retrieved by using reqAppItemListWithCallback: or reqAppItemListWithCallback:andOptions: method:

@interface RDAppBadge : NSObject
//...
-(id<RDCancelable>) reqAppItemListWithCallback:(id<RDApiRequestBadgeAppItemListCallback>) callback
                                    andOptions:(NSDictionary*) options;
 
-(id<RDCancelable>) reqAppItemListWithCallback:(id<RDApiRequestBadgeAppItemListCallback>) callback;
//...
@end

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's dataEntry property contains an array of RDAppBadgeAppInfoItem objects which describes all badges defined for the application on developer portal.

Personal tools
Namespaces

Variants
Actions
Navigation
Toolbox