iOS API Reference

Contents

iOS API Reference#

Best Practices for Common Scenarios#

Description#

This section describes usage patterns and guidelines for common integration scenarios enabled using RaveSocial APIs that venture beyond the drop-in experience found in the included scene pack.

The scene pack provides a built in user profile experience, for example, but you may create an app-specific profile experience and this guide explains some common scenarios you may encounter.

Using App Data Keys for Save Game or Cloud Storage ID#

To get a stable index for data lookup, especially if Rave ID was used in the past, then RaveAppDataKeys is the recommended API to use. Simply implement the protocol RaveAppDataKeysStateObserver.

- (void)appDataKeyStateChanged:(NSString *)selectedKey unresolvedKeys:(NSArray *)unresolvedKeys

By default the selected key returned by this interface will be the current key for the current user. In a typical case, it will be a randomly generated key in a 32 character hex format. If no key had been previously selected for the current application this random key will be the default. The selected key will be non-nil provided that unresolvedKeys is empty, which will usually be the case. When there are unresolved keys, and you are online, then your integration will need to choose between the unresolved keys. Rave will never make a choice between unresolved keys, this is strictly up to the developers discretion.

The integration will choose between unresolved keys when a merge takes place between two users that have already used the current application. At this point either present the user with a choice between the unresolved keys or choose one automatically. With both keys the application can look up information about the two indexes to choose from or present the information to the user. Once a key has been chosen call +[RaveAppDataKeys selectKey:callback:] (see selectKey for more information).

User Profile Scenarios#

Code samples for custom user profile scenarios are provided in SampleRaveProfileScene.m included in your distribution package.

Accessing the current user#

RaveSocial.currentUser is a shortcut method for accessing the current user.

Provided RaveSettings.General.AutoGuestLogin is enabled this value should never be nil, even after a log out operation. You can access a variety of fields to populate user’s profile screen including display name, email, and profile picture URL.

Observing the current user#

New in Rave 3.0.2 is an API to register observers for changes to the current user: -[RaveUsersManager addCurrentUserObserver:]. When a change occurs, usually as the result of an asynchronous operation, all registered observers will be notified with an array of the changed properties of the current user.

It is recommended that you leverage this feature in your custom user profile screen for displayName and pictureURL (or pictureImage), since those values may change as a result of an asynchronous operation that you’ve triggered that didn’t explicitly change those user fields.

Observers should implement the RaveCurrentUserObserver protocol, which consists of one method: -[RaveCurrentUserObserver userChanged:].

- (void)userChanged:(NSArray *)changedKeys {
    if ([changedKeys containsObject:@"displayName"]) {
        //  Update UI with new display name
    } else if ([changedKeys containsObject:@"pictureImage"]) {
        //  Update UI with new profile picture
    } else if ([changedKeys containsObject:@"pictureURL"]) {
        //  Update picture image
    }
}

Displaying the profile picture#

The current user has a reference to the pictureURL, it is always a remotely stored image. It will either be stored on Rave’s servers or on a third party’s server, depending on the source of the image.

On iOS you have the option of fetching the image from URL yourself using RaveSocial.currentUser.pictureURL, or there is a convenience method to do it for you:

id<RaveUser> current = RaveSocial.currentUser;
[current updatePictureImage:^(NSError * error) {
    if (error) {
        [RaveSocial.errorDelegate showError:error];
    } else {
        //  perform some other action with the image
        //  e.g. current.pictureImage
    }
}];

Changing Profile Picture#

There is a common method on all platforms that takes a local file url and pushes the binary data for the image to the Rave backend so that the profile picture is available on any device.

NSString * imageURL = someLocalImageURL;
[RaveSocial.usersManager pushProfilePicture:imageURL withCallback:^(NSError *error) {
     if (error){
         //  do something in the error case
         [RaveSocial.errorDelegate showError:error];
     }
}];

Changing the display name#

New in Rave 3.0.2 is an API to modify the current user without staging the changes in the model. -[RaveUsersManager pushUserChanges:callback:].

RaveUserChanges * changes = [RaveUserChanges userChanges];
changes.displayName = someOtherName;
[RaveSocial.usersManager pushUserChanges:changes callback:^(NSError * error) {
    if (error) {
        // Do something with the error
    }
}];

Use this new method rather than the legacy method -[RaveUsersManager pushCurrent:].

Logging out#

If RaveSettings.General.AutoGuestLogin is enabled a new anonymous user will automatically be created when user logs out. Prior to the logOut completion callback firing it is suggested that you prevent the user from interacting with Rave similar to what is shown in the snippet below.

[RaveSocial.progressDelegate showWithMessage:"Signing out..." andCancelCallback:nil];
[RaveSocial logOut:^(NSError * error) {
    [RaveSocial.progressDelegate dismiss];
    if (error) {
        // handle error logging out
    }
}];

Finding friends via Facebook (or another social network)#

RaveConnectFriendsController was introduced in Rave 3.0.1. It provides a way to simplify connection of UI and logic and is recommended for most integrations where friend-only connection is desired for anonymous and personalized users.

The connect friend controller will sync a user’s friend/contact list against their list of Facebook friends, or list of friends from another social provider, adding the Facebook friends that started to play the game since the last friend sync happened. The friend sync executes automatically on a configurable time interval.

If the current user is already authenticated the controller will also automatically connect the social provider (ie. Facebook) to Rave, so the user can sign in with that social provider as another authentication method.

The friend sync executes opportunistically with a configurable time interval. For an overview of app contacts features, see: Contacts

Creating a controller:

RaveConnectFriendsController * controller = [RaveConnectFriendsController controllerWithPlugin:RaveConnectPluginFacebook];
controller.friendsObsever = self;       //      Assumes self implements RaveConnectFriendsStateObserver

// Only necessary if you want to filter and display error messages
controller.callback = ^(NSError * error) {
    //  display errors as desired
};

Tracking current state:

- (void)onFindFriendsStateChanged:(RaveFriendsControllerState)value {
    // You will also want to update your UI to reflect the state
    switch (value) {
    case RaveFriendsControllerStateNotDownloaded:
        self.downloaded = NO;
        break;
    case RaveFriendsControllerStateDownloading:
        //  do something to indicate busy
        break;
    case RaveFriendsControllerSateDownloaded:
        self.downloaded = YES;
        break;
    }
}

Toggling state:

if (self.downloaded) {
    [self.controller attemptForgetFriends];
} else {
    [self.controller attemptGetFriends]
}

Authenticate with Facebook (or another social network)#

RaveConnectController was introduced in Rave 3.0.1. It provides a way to simplify connection of UI and logic and is recommended for most integrations.

This controller will associate the user’s Facebook (or other social provider) account with their game account for authentication purposes and sync the user’s Facebook (or other social provider) friends who are playing this game with the Rave contact system, adding any new friends as contacts. The friend sync executes automatically on a configurable time interval.

After a user has connected using this controller, they will be able to access their user account by signing in via this social network account on other devices.

For an overview of app contacts features, see: Contacts

Creating a controller:

RaveConnectController * controller = [RaveConnectController controllerWithPlugin:RaveConnectPluginFacebook];
controller.observer = self;  //  Assumes self implements RaveConnectStateObserver

//  Only necessary if you want to filter and display error messages
controller.callback = ^(NSError * error) {
    //  display errors as desired
};

Tracking current state:

- (void)onConnectStateChanged:(RaveConnectControllerState)value {
        switch (value) {
        case RaveConnectControllerStateDisabled:
                //      disable UI
                break;
        case RaveConnectControllerStateConnected:
                self.connected = YES;
                break;
        case RaveConnectControllerStateConnecting:
        //  do something to indicate busy
                break;
        case RaveConnectControllerStateDisconnected:
                self.connected = NO;
                break;
        case RaveConnectControllerStateDisconnecting:
        //  do something to indicate busy
                break;
        }
}

Toggling state:

if (self.connected) {
    [self.controller attemptConnect];
} else {
    [self.controller attemptDisconnect]
}

Opening common scenes#

Opening the Login Scene#

Opening the login scene allows the user to sign in using their BigFish account by default. It also provides the user with a convenient shortcut to the create account scene through a button.

The following sample code shows an example of showing the scene and also capturing the result of any login or account creation that occurs. In the case that a new account is created the result will be successful and the signup data will be valid. For details of the signup data see the appropriate documentation in the BigFishScenePack.

RaveLoginScene * loginScene = [RaveLoginScene scene];
loginScene.signUpDataCallback = ^(RaveCallbackResult result, BigFishSignUpData * signUpData, NSError * error) {
if (result == RaveResultSuccessful) {
        if (signUpData != nil) {
        }
} else if (result == RaveResultCanceled) {
} else {
        [RaveSocial.errorDelegate showError:error];
}
}];
[loginScene show];

The Create Account scene allows the user to create a BigFish account. It also provides the user with a convenient shortcut to the login scene through a button.

The following example code shows an example of showing the scene and also capturing the result of any login or account creation that occurs. In the case that an account is created the result will be successful and the signup data will be valid. For details of the signup data see the appropriate documentation in the BigFishScenePack.

RaveSignUpEmailScene * signUpScene = [RaveSignUpEmail scene];
signUpScene.signUpDataCallback = ^(RaveCallbackResult result, BigFishSignUpData * signUpData, NSError * error) {
if (result == RaveResultSuccessful) {
        if (signUpData != nil) {
        }
} else if (result == RaveResultCanceled) {
} else {
        [RaveSocial.errorDelegate showError:error];
}
}];
[signUpScene show];

You’ll want to show the Find Friends scene if you want an easy way to attract users to attaching Facebook, Google, Phonebook contacts, etc. to their Rave account.

RaveFindFriendsScene * findFriendsScene = [RaveFindFriendsScene scene];
findFriends.sceneCompleteCallback = ^{
// capture when this scene is closed
};
[findFriendsScene show];

RaveSocial API#

class: RaveSocial

header: <RaveSocial/RaveSocial.h>

initializeRave (with launch options and ready callback) - New in 3.1.1#

Initialize Rave when using FBSDKCoreKit for Facebook 4.x and call from your UIApplicationDelegate application:didFinishLaunchingWithOptions:. Will attempt to load config JSON from application bundle:

+ (void)initializeRaveWithLaunchOptions:(NSDictionary *)launchOptions withReadyCallback:(RaveCompletionCallback)readyCallback;

Parameters:

launchOptions - Launch options forwarded from UIApplication delegate, may be nil though that may introduce incorrect behavior from FBSDKCoreKit

readyCallback - Callback when Rave is ready after initializing, which may include some asynchronous operations

initializeRave (with config URL, launch options, and ready callback) - New in 3.1.1#

Initialize Rave when using FBSDKCoreKit for Facebook 4.x and call from your UIApplicationDelegate application:didFinishLaunchingWithOptions::

+ (void)initializeRaveWithConfig:(NSURL *)configURL withLaunchOptions:(NSDictionary *)launchOptions withReadyCallback:(RaveCompletionCallback)readyCallback;

Parameters:

configURL - URL for alternate path to JSON configuration for Rave settings, may be nil

launchOptions - Launch options forwarded from UIApplication delegate, may be nil though that may introduce incorrect behavior from FBSDKCoreKit

readyCallback - Callback when Rave is ready after initializing, which may include some asynchronous operations

handleURL (with URL, source application, and annotation) - New in 3.0.x#

Integration method to forward URL requests from the UIApplicationDelegate for internal Rave usage:

+ (BOOL)handleURL:(NSURL *)url sourceApplication:(NSString *)sourceApplication annotation:(id)annotation;

Parameters:

url - URL forwarded from application delegate

sourceApplication - Source application forwarded from application delegate

annotation - Annotation forwarded from application delegate

Returns: YES if Rave handled the URL request otherwise NO, typically should be returned from the UIApplicationDelegate

initializeRave#

Initialize the SDK:

+ (void)initializeRave

initializeRave (with callback)#

Initialize the SDK and callback on completion:

+ (void)initializeRaveWithReadyCallback:(RaveCompletionCallback)readyCallback

Parameters:

readyCallback - The block to callback when initialization is complete

initializeRaveWithConfig#

Initialize the SDK with a custom JSON config source:

+ (void)initializeRaveWithConfig:(NSURL *)configURL

Parameters:

configURL - A url to the config JSON

initializeRaveWithConfig (with callback)#

Initialize the SDK with a custom JSON config source and callback on completion:

+ (void)initializeRaveWithConfig:(NSURL *)configURL withReadyCallback:(RaveCompletionCallback)readyCallback

Parameters:

configURL - A url to the config JSON

readyCallback - The block to callback when initialization is complete

volatileRaveId#

Returns a Rave Id after initialization call has returned. Value may change after ready callback has fired:

+ (NSString *)volatileRaveId

Returns: Best guess UUID for the Rave user prior to completing initialization

connectTo#

Attention

Rather than implementing a fully custom control for connecting your users we suggest as best practice that you instead use your custom UI to wrap one of our connect controllers. Please read Adding a Facebook (or another social provider) button to your App.

Connect the current user to an authentication provider

+ (void)connectTo:(NSString *)pluginKeyName callback:(RaveCompletionCallback)callback

Parameters:

pluginKeyName - The KeyName of the authentication provider plugin

callback - A completion callback

loginWith#

Attention

Rather than implementing a fully custom control for connecting your users we suggest as best practice that you instead use your custom UI to wrap one of our connect controllers. Please read Adding a Facebook (or another social provider) button to your App.

Logs in with an authentication provider. Make sure the current user isn’t already authenticated in before use. This will either connect the current anonymous user to the provider, or it will create a new session.

+ (void)loginWith:(NSString *)pluginKeyName callback:(RaveCompletionCallback)callback

Parameters:

pluginKeyName - The KeyName of the authentication provider plugin

callback - A completion callback

disconnectFrom#

Disconnects the current user from an authentication provider

+ (void)disconnectFrom:(NSString *)pluginKeyName callback:(RaveCompletionCallback)callback

Parameters:

pluginKeyName - The keyname of the plugin

callback - A completion callback

logOut (with callback) - New parameter in 3.0.x#

Logs the current user out of Rave. Deletes the current session and clears the cache. If the setting RaveSettings.General.AutoGuestLogin is enabled, a new guest account will be logged in immediately.

Providing a null callback will result in operations such as automatic guest login and session deletion happening asynchronously. To guarantee that a race does not happen with any other authentication actions, it is highly recommended that a listener be set and that no other Rave APIs be called until the listener has called back.

+ (void)logOut:(RaveCompletionCallback) callback;

Parameters:

callback - A completion callback

loginAsGuest#

Logs in as a guest account. Do not call this if already logged in. This will not work if the setting RaveSettings.General.AutoGuestLogin is enabled, as guest login is controlled by Rave in that case and cannot be explicitly controlled.

+ (void)loginAsGuest:(RaveCompletionCallback)callback

Parameters:

callback - A completion callback

currentUser#

Gets the current user from cache if the user is logged in and cached user data is available:

+ (id<RaveUser>)currentUser

checkReadinessOf#

Checks the state of an authentication provider to determine if it is ready to use A plugin is “Ready” if it has a token available from the provider and the current user is connected with a matching ID to the token:

+ (void)checkReadinessOf:(NSString *)pluginKeyName callback:(RaveReadinessCallback)callback

Parameters:

pluginKeyName - The KeyName of the authentication provider plugin

callback - A readiness callback

isPluginReady#

Returns the cached value of the last time an authentication provider was checked for readiness. A plugin is “Ready” if it has a token available from the provider and the current user is connected with a matching ID to the token:

+ (BOOL)isPluginReady:(NSString *)pluginKeyName

Parameters:

pluginKeyName - The KeyName of the authentication provider plugin

Returns: true if the plugin is ready, false if not

isLoggedIn#

Returns if there is an active session in any state (Guest, Authenticated or otherwise).

+ (BOOL)isLoggedIn

Returns: true if there is an active session, false if not

isLoggedInAsGuest#

Returns if there is an active session and the session is for a user in an anonymous (guest) state:

+ (BOOL)isLoggedInAsGuest

Returns: true if the current user is a guest, false if not or if there is no session

isPersonalized#

Returns if there is an active session and the session is for a user in personalized state:

+ (BOOL)isPersonalized

Returns: true if the current user is personalized, false if not or if there is no session

isAuthenticated#

Returns if there is an active session and the session is for a user in authenticated state:

+ (BOOL)isAuthenticated

Returns: true if the current user is authenticated, false if not or if there is no session

isNetworkAvailable#

Returns if there is a network connection available:

+ (BOOL)isNetworkAvailable

Parameters:

context - An Android Context

Feature Manager Access#

All feature managers are available through the RaveSocial class.

achievementsManager - Achievements Manager

contactsManager - Contacts Manager

giftsManager - Gifts Manager

leaderboardsManager - Leaderboards Manager

promotionsManager - Promotions Manager

sharingManager - Sharing Manager

usersManager - Users Manager

AppDataKeys API#

header: <RaveSocial/RaveAppDataKeysManager.h>

class: RaveAppDataKeysManager

App data keys can be used to index cloud or other back-end storage data to a user’s account for a given application. App Data Keys are randomly generated IDs for each user in a 32 character hex format. When the user’s account is merged and both the source and target user of the merge have an active key for a game, the keys will enter an unresolved state and no key will be selected. This API provides the unresolved keys so that an application can provide a selection, either automatically (set by the developer) or via user input. Once a key is selected, the remaining unresolved keys will become rejected. Rejected keys can be selected at any time.

Any key in the list of all available can be selected at any time.

Note

Although the Rave SDK will work correctly in a case where no key is selected, we strongly recommend that the game ensures that a key is selected at all times during a game session. The reason is that when no key is selected, the player’s progress (or other important game data) is not indexed, and therefore progress could be lost. One way to do this is to check whether ADK is selected on game open, and during a network switch.

RaveAppDataKeysStateObserver#

Tip

Best Practice - Every application should be using this API to retrieve the selected app data key or resolve a selected key from the list of unresolved keys.

Implement RaveAppDataKeysStateObserver observer protocol when using the app data keys system to track save keys for cloud storage

appDataKeyStateChanged#

This method will be called after init to establish your current identity or if you are currently in an unresolved state. It will also be called when the system has detected that, after a merge, the current user has no selected app data key. This means that both users in the merge had a selected key and a determination needs to be made about which merged key should become the selected key. See RaveAppDataKeys(Manager) for details on retrieving the unresolved keys and selecting the valid key.

- (void)appDataKeyStateChanged:(NSString *)selectedKey unresolvedKeys:(NSArray *)unresolvedKeys;

Parameters:

  • selectedKey - The key selected for this application and user

  • unresolvedKeys - Keys that need to be resolved, there will always be zero or two or more

Callbacks#

RaveAppDataKeysStateCallback#

Callback to provide all possible details for application data keys for this user and application:

typedef void (^RaveAppDataKeysStateCallback)(NSString * selectedKey, NSArray * rejectedKeys, NSArray * unresolvedKeys, NSError * error);

Parameters:

  • selectedKey - The key selected for this application and user

  • rejectedKeys - Keys that have been rejected for use as the selected key

  • unresolvedKeys - Keys that need to be resolved, there will always be zero or two or more

  • error - An error or nil

RaveAppDataKeysCallback#

Callback to fetch a subset of the app data keys information:

typedef void (^RaveAppDataKeysCallback)(NSArray * keys, NSError * error);

Parameters:

  • keys - The array of requested keys

  • error - An error or nil

RaveAppDataKeyCallback#

Callback to fetch the selected key:

typedef void (^RaveAppDataKeyCallback)(NSString * selectedKey, NSError * error);

Parameters:

  • selectedKey - The app data key selected for the current user

  • error - An error or nil

RaveAppDataKeysManager#

Manages app data keys

setStateObserver#

Set an instance of the appDataKeysStatusObserver:

- (void)setStateObserver:(id<RaveAppDataKeysStateObserver>)stateObserver;

Paramaters:

stateObserver - Observer for changes in status

lastSelectedKey#

Cached last selected key, if any. When possible prefer key from state observer:

- (NSString *)lastSelectedKey;

Returns: Last selected app key or nil

fetchCurrentState#

Fetch the selected key, rejected keys, and unresolved keys for this application:

- (void)fetchCurrentState:(RaveAppDataKeysStateCallback)callback;

Parameters:

callback - Provides information about data keys for the current application or an error

fetchUnresolved#

Fetch the set of unresolved keys, will either have a count of zero or two or more:

- (void)fetchUnresolved:(RaveAppDataKeysCallback)callback;

Parameters:

callback - Callback supplying the keys or an error

fetchSelected#

Fetch the currently selected key for the user. Will be nil unless a key has been selected:

- (void)fetchSelected:(RaveAppDataKeyCallback)callback;

Parameters:

callback - Callback supplying the selected key or an error

fetchAvailable#

Fetch values available to be used as keys - This list will included every Rave identity associated with the current account:

- (void)fetchAvailable:(RaveAppDataKeysCallback)callback;

Parameters:

callback - Callback supplying the requested keys or an error

selectKey#

Change the selected key to the specified value:

- (void)selectKey:(NSString *)selectedKey callback:(RaveCompletionCallback)callback;

Parameters:

  • selectedKey - The desired value of the new selected key

  • callback - Callback suppyling an error or nil on success

deactivateKey#

Deactivates a key - Requires active network and only works for keys which are selected, rejected or unresolved:

- (void)deactivateKey:(NSString *)key callback:(RaveCompletionCallback)callback;

Parameters:

  • key - The key to deactivate, must be 32 character hex format

  • callback - Callback suppyling an error or nil on success

fetchUserKey#

Returns an App Data Key when given a UUID. Essentially a lookup based on UUID:

- (void)fetchUserKey:(NSString *)raveId callback:(RaveAppDataKeyCallback)callback;

Parameters:

  • raveId - The user’s raveID you wish to look up

  • callback - A callback to be called when the operation completes. Contains a selected key or an error

fetchUserKeySet#

Fetch a set of keys given an array of RaveIDs:

- (void)fetchUserKeySet:(NSArray <NSString *>*)raveIds callback:(RaveAppDataKeySetCallback)callback;

Parameters:

  • raveIds - A List of desired Rave IDs

  • callback - A callback supplying a list of app data keys or an error

fetchUserKeySetForContacts#

Fetch the current user’s contacts app data keys:

- (void)fetchUserKeySetForContacts:(RaveAppDataKeySetCallback)callback;

Parameters:

  • callback - a callback to be called when the operation completes. Contains an array of app data key and rave ID pairs or an error

Controllers API#

RaveConnectFriendsController#

class: RaveConnectFriendsController

header: <RaveSocial/RaveConnectFriendsController.h>

Enum RaveFriendsControllerState#

  • RaveFriendsControllerStateNotDownloaded: Friends syncing is not enabled

  • RaveFriendsControllerStateDownloading: Friends sycning is in progress

  • RaveFriendsControllerStateDownloaded: Friends sycning is enabled

Protocol RaveConnectFriendsStateObserver#

Implement this observer to track state changes in the controller to keep your UI up-to-date:

- (void)onFindFriendsStateChanged:(RaveFriendsControllerState)value;

Parameters:

value - Latest state value

controllerWithPlugin#

Constructor for new friends controller:

+(RaveConnectFriendsController *)controllerWithPlugin:(NSString *)pluginKeyName;

Parameters:

pluginKeyName - Key for the plugin to use with this controller instance

Returns: Instance of RaveConnectFriendsController for the plugin specified

setFriendsObserver#

Implement RaveConnectFriendsStateObserver and set your observer instance in the controller:

- (void)setFriendsObserver:(RaveConnectFriendsStateObserver)friendsObserver;

Parameters:

friendsObserver - Reference to object implementing the state observer. Recommend you have a unique observer for each controller/plugin pair.

attemptGetFriends#

Attempt to sync friends asynchronously. Checks internal logic to ensure that the plugin is enabled and that friends haven’t already been synced. If the user is authenticated will attempt to connect the plugin to the curent user in addition to syncing friends. Track changes to state through the observer:

-(void)attemptGetFriends;

attemptForgetFriends#

Attempt to stop syncing friends asynchronously. Checks internal logic to ensure that the plugin is enabled and that friends have been synced. If the user is authenticated this call will attempt to disconnect the plugin from the current user in addition to stopping syncing. Track changes to state through the observer:

-(void)attemptForgetFriends;

RaveConnectController#

class: RaveConnectController

header: <RaveSocial/RaveConnectController.h>

Enum RaveConnectControllerState#

  • RaveConnectControllerStateDisabled : Controller is disabled, plugin isn’t available

  • RaveConnectControllerStateConnected : Controller is connected, plugin is ready to use

  • RaveConnectControllerStateConnecting : Controller is in the process of asynchronously attempting to connect, plugin is not ready

  • RaveConnectControllerStateDisconnected : Controller is disconnected, plugin is not ready

  • RaveConnectControllerStateDisconnecting : Controller is in the process of asynchronously attempting to disconnect, plugin is not ready

Protocol RaveConnectStateObserver#

Implement this observer to track state changes to the controller to keep your UI up-to-date:

-(void)onConnectStateChanged:(RaveConnectControllerState)value;

Parameters:

value - Latest state value

controllerWithPlugin#

Constructor for instances of RaveConnectController:

+ (instancetype)controllerWithPlugin:(NSString *)pluginKeyName;
+ (instancetype)controllerWIthPlugin:(NSString *)pluginKeyName autoUpdate:(BOOL)autoUpdate;

Parameters:

pluginKeyName - Key name for plugin to use for this controller

autoUpdate - True to automatically update connect state when observer is set (defaults to false)

Returns: Instance of RaveConnectController for the plugin specified

setConnectObserver#

Implement RaveConnectStateObserver and set your instance in the controller using setObserver:

- (void)setConnectObserver:(RaveConnectStateObserver)observer;

Parameters:

observer - Observer instance. Recommended that you have a different instance per plugin/controller pair.

attemptConnect#

Attempt to connect asynchronously. Checks internal logic to ensure that the plugin is enabled and plugin isn’t already connected. Track changes to state through the observer:

-(void)attemptConnect;

attemptDisconnect#

Attempt to disconnect asynchronously. Checks internal logic to ensure that the plugin is connected. Track changes to state through the observer:

-(void)attemptDisconnect;

updateConnectState#

Refresh the connect state of the controller with the plugin. Track changes to state through the observer:

- (void)updateConnectState;

Called automatically if autoUpdate is true for this controller.

setPluginKeyName#

Set the pluginKeyName for this controller. Typically shouldn’t be changed after construction:

- (void)setPluginKeyName:(NSString *)pluginKeyName;

Parameters:

pluginKeyName - Key name for plugin to use

setCallback#

Set callback for asynchronous operations on this controller. Used to track errors that occur in the course of normal operations:

- (void)setCallback:(RaveCompletionCallback)callback;

Parameters:

callback - Completion callback for error handling

Authenticated Merging API#

header: RaveSocial/RaveMergePolicy.h

There are several important decision points that can occur during an authenticated merge that need to be handled carefully for a successful integration. As a result, authenticated merging is not enabled unless an integrator sets an instance of a RaveMergePolicy. A demonstration policy will be provided in your accompanying scene pack and demo.

To enable merging set an instance of RaveMergePolicy via +[RaveSocial setMergePolicy:]. A merge attempt will typically be triggered during a connect operation when attempting to add an authentication source during an account. See Account conflict resolution for more information about conflict scenarios. You are strongly discouraged from automatically deciding to accept the merge as two accounts cannot be unmerged once merged. This obviously could have unintended effects on a player’s progress.

RaveMergeDecisionListener#

When a merge policy is invoked you’re given a listener of this type that the SDK uses to determine when your user has decided whether to accept the potential merge.

Use this callback after the user has decided whether to accept the potential merge with the result of their decision.

typedef void (^RaveMergeDecisionCallback)(BOOL shouldMerge);

Parameters:

shouldMerge - True if the user decided to proceed with the merge, otherwise false

RaveMergeUser#

A typical RaveUser with one additional field added - selectedAppDataKey so that you can potentially preview save game data for the other user.:

NSString * selectedAppDataKey;

RaveMergePolicy#

This policies method will be invoked when a decision point is reached for triggering a merge during an account conflict.

void makeMergeDecision:(id<RaveMergeUser>)targetUser callback:(RaveMergeDecisionCallback)callback;

Parameters:

targetUser - User the current user will be merged into. Some fields will be filled out, such as displayName and profile picture URL so that you can help the user decide whether or not they mean to merge.

callback - Merge decision callback, use after user has indicated whether they want to continue the merge. You are strongly discouraged from automatically deciding to merge.

Note

See BigFishMergePolicy in BigFishScenePack package for a possible default implementation of a merge policy

Achievements API#

Note

In order to use achievements in your application, you must define your achievements in the Rave Developer Portal. See the Achievements section in the portal documentation for instructions on how to create acheivements.

class: RaveAchievements

header: <RaveSocial/RaveAchievements.h>

getAchievementByKey#

Retrieve a RaveAchievement from the local cache based on key.

- (id<RaveAchievement>)getAchievementByKey:(NSString *)key;

Parameters:

key - Key for a matching achievement

Returns: Reference to a RaveAchievement or nil if no match is found

updateAchievements#

Retrieve all Rave achievements from the server and update the local cache with the retrieved data.

- (void) updateAchievements:(RaveCompletionCallback)callback;

Parameters:

callback - Callback to call when the update is completed

getAchievements#

Retrieves all achievements stored in the local cache.

@property (nonatomic, retain) NSArray * achievements;

Returns: A NSArray of RaveAchievement objects.

unlockAchievement#

Unlock an achievement for the current user, specified by achivement key.

- (void) unlockAchievement:(NSString *)achievementKey withCallback:(RaveCompletionCallback)callback;

Parameters:

achievementKey - A string containing the key of the achievement to be unlocked

callback - Callback to call when the server has completed the unlock achievement operation

Contacts API#

class: RaveContacts

header: <RaveSocial/RaveContacts.h>

startFriendsSyncFor#

Method to start updating Rave contacts using the service specified

This typically will require the user to authenticate using that service

Will enable future updates to happen automatically based on RaveSettings.General.ContactsUpdateInterval Will automatically be called by +[RaveSocial connectTo] if RaveSettings.General.AutoSyncFriends includes a key matching pluginKeyName:

- (void)startFriendsSyncFor:(NSString *)pluginKeyName callback:(RaveCompletionCallback)callback;

Parameters:

pluginKeyName - The key for the plugin to sync friends with

callback - Callback will return nil on success otherwise an error

Usage example:

if ([[RaveAuthentication getCurrentTokenFrom:RaveConnectPluginFacebook] length] > 0) {
    [RaveContacts startFriendSyncFor:RaveConnectPluginFacebook callback:^(NSError * error) {
        if (error != nil) {
            //  do something with the error
        }
    }];
}

stopFriendSyncFor#

Method to stop updating Rave contacts using the service specified

Disables future syncing for the service specified by pluginKeyName:

- (void)stopFriendsSyncFor:(NSString *)pluginKeyName;

Parameters:

pluginKeyName - The key for the plugin to sync friends with

getContactByRaveId#

Retrieve a RaveContact from the local cache based on user id.

- (id<RaveContact>)getContactByRaveId:(NSString *)raveId;

Parameters:

raveId - User id to key the search for a matching contact

Returns: Reference to a RaveContact or nil if no match is found

updateAll#

Retrieve all Rave contacts from the server and update the local cache with the retrieved data.

- (void)updateAll:(RaveCompletionCallback)callback;

Parameters:

callback - Callback to call when the update is completed

updateAllUsingThisApplication#

Retrieve all Rave contacts from the server that also use the current application and update the local cache with the retrieved data.

- (void)updateAllUsingThisApplication:(RaveCompletionCallback)callback;

Parameters:

callback - Callback to call when the update is completed

updateAllUsingApplication#

Retrieve all Rave contacts from the server that also use the specified application and update the local cache with the retrieved data.

- (void)updateAllUsingApplication:(NSString *)appId withCallback:(RaveCompletionCallback)callback;

Parameters:

appId - Rave Application ID of the specified application

callback - Callback to call when the update is completed

getAll#

Retrieves all contacts stored in your Rave account from the local cache.

@property (nonatomic, readonly) NSOrderedSet * all;

Returns: A NSOrderedSet of RaveContact objects.

getAllUsingThisApplication#

Retrieves all contacts stored in your Rave account that also use the current application from the local cache.

@property (nonatomic, readonly) NSOrderedSet * allUsingThisApplication;

Returns: A NSOrderedSet of RaveContact objects.

getAllUsingApplication#

Retrieves all contacts stored in your Rave account that also use the specified application from the local cache.

- (NSOrderedSet *)getAllUsingApplication:(NSString *)appId;

Parameters:

appId - Rave Application ID of the specified application

Returns: A NSOrderedSet of RaveContact objects.

updateFacebook#

Retrieve all Rave contacts that originated from Facebook and from the server and update the local cache with the retrieved data.

- (void)updateFacebook:(RaveCompletionCallback)callback;

Parameters:

callback - Callback to call when the update is completed

getFacebook#

Retrieves all contacts that originated from Facebook stored in your Rave account from the local cache.

@property (nonatomic, readonly) NSOrderedSet * facebook;

Returns: A NSOrderedSet of RaveContact objects.

deleteContact#

Delete a specificed Rave contact and notify the server of the deletion.

- (void) deleteContact:(NSString *)userUuid withCallback:(RaveCompletionCallback)callback;

Parameters:

userUuid - Rave User ID of the specified contact

callback - Callback to call when the server has completed the delete operation

addContactsByUsername#

Manually add contacts by username. Username is any arbitrary string that is used to identify the contact.

- (void) addContactsByUsername:(NSArray*)usernames withCallback:(RaveCompletionCallback)callback;

Parameters:

usernames - A NSArray of usernames to add as contacts

callback - Callback to call when the server has completed the add contact operation

fetchAllExternal#

Fetch all external contacts/friends from all social networks and third party providers and filter them as specified.

- (void)fetchAllExternal:(enum RaveContactsFilter)filter withCallback:(RaveContactsCallback)callback;

Parameters:

filter - Filter to use for fetching contacts. RaveContactsFilter enum: RaveContactsFilterIncludeAll, RaveContactsFilterIncludeOnlyUsingApp, RaveContactsFilterExcludeUsingApp

callback - Callback to call when the server has completed the fetch operation and returns the list of fetched contacts

fetchExternalFrom#

Fetch all external contacts/friends from a contacts provider and filter them as specified.

- (void)fetchExternalFrom:(NSString *)pluginKeyName filter:(enum RaveContactsFilter)filter withCallback:(RaveContactsCallback)callback;

Parameters:

pluginKeyName - Contacts provider plugin keyname

filter - Filter to use for fetching contacts. RaveContactsFilter enum: RaveContactsFilterIncludeAll, RaveContactsFilterIncludeOnlyUsingApp, RaveContactsFilterExcludeUsingApp

callback - Callback to call when the server has completed the fetch operation and returns the list of fetched contacts

Friends API#

Deprecation Warning

As of v3.13.0, this API is deprecated and planned for removal in a future release. We strongly advise that you adjust your code dependencies to avoid potential disruptions, as continuous updates and support for this API will not be available after its removal.

class: RaveFriendsManager#

Main API for accessing Rave friends

header: <RaveSocial/RaveFriendsManager.h>

convenience class: RaveFriends convenience header: <RaveSocial/RaveFriends.h>

friendsListQuery#

Start query for friends list:

- (id<RaveListQueryBuilder>)friendsListQuery:(NSString *)listKey;

Parameters:

listKey - Key for the friends list to query

Returns: Reference to a list query builder for filtering friends

updateFriendsList#

Update cached list of friends for given key:

- (void)updateFriendsList:(NSString *)listKey callback:(RaveCompletionCallback)callback;

Parameters:

listKey - Key identifier for list being updated

callback - Callback indicating success of operation

removeFriend#

Remove friend from specified list:

- (void)removeFriend:(NSString *)listKey friendId:(NSString *)friendId callback:(RaveCompletionCallback)callback;

Parameters:

listKey - Key identifier for list friend is being removed from

friendId - Rave id for friend being removed

callback - Callback indicating success of the operation

sendFriendRequest#

Send friend request to another Rave user:

- (void)sendFriendRequest:(NSString *)listKey reference:(RaveUserReference *)reference callback:(RaveCompletionCallback)callback;

Parameters:

listKey - Identifier for list to send friend request through

reference - Reference to user to befriend

callback - Callback indicating success of the operation

fetchSentFriendRequests#

Fetch list of pending friend requests sent by the current user:

- (void)fetchSentFriendRequests:(NSString *)listKey callback:(RaveFriendRequestCallback)callback;

Parameters:

listKey - Identifier for the list to query

callback - Callback providing the list of results or an error

cancelFriendRequest#

Cancel a pending sent friend request:

- (void)cancelFriendRequest:(NSString *)listKey raveId:(NSString *)raveId callback:(RaveCompletionCallback)callback;

Parameters:

listKey - Identifier for the list to remove the friend request from

raveId - Rave id for the user that the request is being canceled for

callback - Callback indicating success of the operation

fetchReceivedFriendRequests#

Fetch list of pending friend requests sent by the current user:

- (void)fetchReceivedFriendRequests:(NSString *)listKey callback:(RaveFriendRequestCallback)callback;

Parameters:

listKey - Identifier for the list to query

callback - Callback providing the list of results or an error

acceptFriendRequest#

Accept received friend request:

- (void)acceptFriendRequest:(NSString *)listKey friendId:(NSString *)friendId callback:(RaveCompletionCallback)callback;

Parameters:

listKey - Identifier for the list to accept friend request in

friendId - Rave id for user accepting friend request from

callback - Callback indicating success of the operation

rejectFriendRequest#

Reject received friend request:

- (void)rejectFriendRequest:(NSString *)listKey raveId:(NSString *)raveId callback:(RaveCompletionCallback)callback;

Parameters:

listKey - Identifier for the list to accept friend request in

raveId - Rave id for user accepting friend request from

callback - Callback indicating success of the operation

Query Recipes#

Now you can filter friends and followers with query builders. For example if you want to find the first ten users alphabetically that have the name “Frank” you would use the following code snippet:

[[[[[[RaveSocial.friendsManager friendsListQuery:@"ExampleListKey"] orderBy:RaveRelationshipOrderByRealName] where:RaveRelationshipWhereRealName] like:@"Frank*"] limit:10] get]

Or if you wanted to find the third person with the displayName “BubbleGum” this snippet would serve:

[[[[[RaveSocial.friendsManager friendsListQuery:@"ExampleListKey"] where:RaveRelationshipWhereDisplayName] equals:@"BubbleGum"] offset:2 limit:1] get]

protocol: RaveRelationshipQueryBuilder#

A query builder to query lists of relationships

get#

Retrieve the query results from the chain of builder calls:

- (NSArray *)get;

Returns: The filtered query results

protocol: RaveRelationshipSearchQueryBuilder#

A query builder providing search features

like#

An SQL standard ‘WHERE field LIKE’ clause:

- (id<RaveRelationshipListQueryBuilder>)like:(NSString *)pattern;

Parameters:

pattern - The standard SQL LIKE clause

Returns: A list query builder

equals#

An SQL standard ‘WHERE field ==’ clause:

- (id<RaveRelationshipListQueryBuilder>)equals:(NSString *)pattern;

Parameters:

pattern - The stander SQL ‘WHERE field ==’ clause

Returns: A list query builder

protocol: RaveRelationshipListQueryBuilder#

A query builder providing filtering features

where#

Add a standard SQL ‘WHERE’ clause - May only be used once per field:

- (id<RaveRelationshipSearchQueryBuilder>)where:(RaveRelationshipWhere)field;

Parameters:

field - The field to match on

Returns: A search query builder

offset#

The result starting offset - Only one offset is allowed in a query builder chain:

- (id<RaveRelationshipListQueryBuilder>)offset:(NSUInteger)offset limit:(NSUInteger)limit;

Parameters:

offset - The offset, starting at 0

limit - The limit value

Returns: A list query builder

limit#

The result limit - Only one limit is allowed in a query builder chain:

- (id<RaveRelationshipListQueryBuilder>)limit:(NSUInteger)limit;

Parameters:

limit - The limit value

Returns: A list query builder

orderBy#

The result order - Only one orderBy is allowed in a query builder chain:

- (id<RaveRelationshipListQueryBuilder>)orderBy:(RaveRelationshipOrderBy)field;

Parameters:

field - The field to order by

Returns: A list query builder

Followers API#

Deprecation Warning

As of v3.13.0, this API is deprecated and planned for removal in a future release. We strongly advise that you adjust your code dependencies to avoid potential disruptions, as continuous updates and support for this API will not be available after its removal.

class: RaveFollowersManager#

Main API for accessing Rave followers

header: <RaveSocial/RaveFollowersManager.h>

convenience class: RaveFollowers convenience header: <RaveSocial/RaveFollowers.h>

updateFollowingList#

Update following list for given key:

- (void)updateFollowingList:(NSString *)listKey callback:(RaveCompletionCallback)callback;

Parameters:

listKey - Identifier for list to update

callback - Callback indicating success of the operation

followingListQuery#

Query following list for given key:

- (id<RaveRelationshipListQueryBuilder>)followingListQuery:(NSString *)listKey;

Parameters:

listKey - Identifier for the list to query

Returns: List query builder for given list

updateFollowersList#

Update followers list for given key:

- (void)updateFollowersList:(NSString *)listKey callback:(RaveCompletionCallback)callback;

listKey - Identifier for list to update

callback - Callback indicating success of the operation

followersListQuery#

Query followers list for given key:

       - (id<RaveRelationshipListQueryBuilder>)followersListQuery:(NSString *)listKey;

**Parameters:**

listKey - Identifier for the list to query

Returns: List query builder for given list

followUser#

Follow a user:

- (void)followUser:(NSString *)listKey reference:(RaveUserReference *)reference callback:(RaveCompletionCallback)callback;

Parameters:

listKey - Identifier for the list to add the followee to

reference - Reference to Rave user

callback - Callback indicating success of the operation

unfollowUser#

Unfollow a user:

- (void)unfollowUser:(NSString *)listKey raveId:(NSString *)raveId callback:(RaveCompletionCallback)callback;

Parameters:

listKey - Identifier for the list to remove the followee from

raveId - Rave id for the user to unfollow

callback - Callback indicating success of the operation

Query Recipes#

Now you can filter friends and followers with query builders. For example if you want to find the first ten users alphabetically that have the name “Frank” you would use the following code snippet:

[[[[[[RaveSocial.friendsManager friendsListQuery:@"ExampleListKey"] orderBy:RaveRelationshipOrderByRealName] where:RaveRelationshipWhereRealName] like:@"Frank*"] limit:10] get]

Or if you wanted to find the third person with the displayName “BubbleGum” this snippet would serve:

[[[[[RaveSocial.friendsManager friendsListQuery:@"ExampleListKey"] where:RaveRelationshipWhereDisplayName] equals:@"BubbleGum"] offset:2 limit:1] get]

protocol: RaveRelationshipQueryBuilder#

A query builder to query lists of relationships

get#

Retrieve the query results from the chain of builder calls:

- (NSArray *)get;

Returns: The filtered query results

protocol: RaveRelationshipSearchQueryBuilder#

A query builder providing search features

like#

An SQL standard ‘WHERE field LIKE’ clause:

- (id<RaveRelationshipListQueryBuilder>)like:(NSString *)pattern;

Parameters:

pattern - The standard SQL LIKE clause

Returns: A list query builder

equals#

An SQL standard ‘WHERE field ==’ clause:

- (id<RaveRelationshipListQueryBuilder>)equals:(NSString *)pattern;

Parameters:

pattern - The stander SQL ‘WHERE field ==’ clause

Returns: A list query builder

protocol: RaveRelationshipListQueryBuilder#

A query builder providing filtering features

where#

Add a standard SQL ‘WHERE’ clause - May only be used once per field:

- (id<RaveRelationshipSearchQueryBuilder>)where:(RaveRelationshipWhere)field;

Parameters:

field - The field to match on

Returns: A search query builder

offset#

The result starting offset - Only one offset is allowed in a query builder chain:

- (id<RaveRelationshipListQueryBuilder>)offset:(NSUInteger)offset limit:(NSUInteger)limit;

Parameters:

offset - The offset, starting at 0

limit - The limit value

Returns: A list query builder

limit#

The result limit - Only one limit is allowed in a query builder chain:

- (id<RaveRelationshipListQueryBuilder>)limit:(NSUInteger)limit;

Parameters:

limit - The limit value

Returns: A list query builder

orderBy#

The result order - Only one orderBy is allowed in a query builder chain:

- (id<RaveRelationshipListQueryBuilder>)orderBy:(RaveRelationshipOrderBy)field;

Parameters:

field - The field to order by

Returns: A list query builder

Groups API#

Deprecation Warning

As of v3.13.0, this API is deprecated and planned for removal in a future release. We strongly advise that you adjust your code dependencies to avoid potential disruptions, as continuous updates and support for this API will not be available after its removal.

class: RaveGroups

header: <RaveSocial/RaveGroups.h>

getGroup#

Retrieve a RaveGroup information object with a specified groupAddress parameter.

- (void)getGroup:(NSString *)groupAddress callback:(RaveGroupCallback)callback;

Parameters:

groupAddress - String representing the address of the group info that is to be accessed.

callback - The callback containing the group search result.

createGroup#

Create a RaveGroup object and register it with the API service. Currently, all created groups will be public groups and will be scoped to the current application. This method form will create a Group with an auto-generated keyname.

- (void)createGroup:(NSString *)displayName callback:(RaveGroupCallback)callback;

Parameters:

displayName - String containing the name of the group to be displayed to users.

callback - The callback containing the group search result.

Create a RaveGroup object with a specified key and register it with the API service. Currently, all created groups will be public groups and will be scoped to the current application. This method form will create a Group with keyname specified in the second paramer.

- (void)createGroup:(NSString *)displayName withKeyname:(NSString *)keyname callback:(RaveGroupCallback)callback;

Parameters:

displayName - String containing the name of the group to be displayed to users.

keyname - String used uniquely identify a group. This keyname is used to form the full Group Address used to access any group.

callback - The callback containing the group search result.

deleteGroup#

Remove the associated group object records from the Rave API service.

- (void)deleteGroup:(RaveCompletionCallback)callback;

Parameters:

callback - Callback to call when the delete is completed

updateGroup#

Update the RaveGroup object’s current state with Rave API service.

- (void)updateGroup:(RaveGroupChanges*)changes callback:(RaveCompletionCallback)callback;

Parameters:

changes - The changes to make to the group.

callback - Callback to call when the update is completed

getMembers#

Retrieves all members that have joined this group.

@property (nonatomic, readonly) NSOrderedSet * getGroupMembers;

Returns: A NSOrderedSet of RaveGroupMember objects.

addMembers#

A method to add a list of RaveUserReferences objects to the group.

- (void)addMembers:(NSOrderedSet *) members callback:(RaveCompletionCallback)callback;

Parameters:

members - An NSOrderedSet reference containing a list of referenced RaveUserReferences objects to be added to the group for membership.

callback - Callback to call when the members have been added.

removeMember#

Removes a RaveGroupMember from the membership of the group and update the removal on the Rave API service. Removed contacts can no longer participate in group activity:

- (void)removeMember:(RaveGroupMember *) member callback:(RaveCompletionCallback)callback;

Parameters:

member - A RaveGroupMember object representing the user contact to have their membership status removed from this group.

callback - Callback to call when the members have been removed.

createJoinRequest#

Requests to join the group by passing in a reference to a RaveContact object.:

- (void)createJoinRequest:(RaveCompletionCallback)callback;

Parameters

callback - Callback to call when the request has been created.

Returns: A JoinRequest object representing the request to join the group.

acceptJoinRequest#

Accept a RaveJoinRequest object reference to allow a RaveUser to join the group. User that activates this method must be the Group admin.:

- (void)acceptJoinRequest:(RaveJoinRequest *) request callback:(RaveCompletionCallback) callback;

Parameters:

request - A JoinRequest object reference representing the request to be granted to the group

callback - Callback to call when the acceptance is completed

getJoinRequests#

Lists all outstanding requests to join the group. User that activates this method must be the Group admin.

- (void)getJoinRequests:(RaveJoinRequestsCallback)callback;

Parameters:

callback - A callback containing fetched join requests.

removeJoinRequest#

Reject a RaveJoinRequest object reference to deny a RaveUser membership to join the group. User that activates this method must be the Group admin.:

- (void)removeJoinRequest:(RaveJoinRequest *)request callback:(RaveCompletionCallback)callback;

Parameters:

request - A RaveJoinRequest object reference representing the request to be denied to the group

callback - Callback to call when the removal is completed

createGroupInvite#

Invites a RaveUser to join the group. User that activates this method must be the Group admin.:

- (void)createGroupInvite:(RaveUserReference *) invitee callback:(RaveCompletionCallback)callback;

Parameters

invitee - A RaveUserReference object reference representing the user that is being invited to join the RaveGroup object.

callback - A callback to call when the group invite has been created.

acceptGroupInvite#

Accept a RaveGroupInvite object reference to confirm a RaveUser’s invitation to join the group. User that activates this method must be the invitee.:

- (void)acceptGroupInvite:(RaveGroupInvite *)invitation callback:(RaveCompletionCallback)callback;

Parameters:

invitation - A GroupInvite object reference representing the invitation to join the group

callback - Callback to call when the acceptance is completed

getGroupInvites#

Lists all outstanding invitations to the group

- (void)getGroupInvites:(NSString*)groupAddress callback:(RaveGroupInvitesCallback)callback;

Paramters:

groupAddress - The address of the group to fetch invites for.

callback - A callback containing group invites.

removeGroupInvite#

Removes an invitation join a group

Reject a RaveGroup object reference to not accept membership to join a group. User that activates this method must be the invitee.

- (void)removeGroupInvite:(RaveGroupInvite *)invitation callback:(RaveCompletionCallback)callback;

Parameters:

request - A RaveGroupInvite object reference representing the membership invitation that the user wants to reject.

callback - Callback to call when the removal is completed

isMember#

Checks to see if a RaveUser is a member of a group or role within the group

- (BOOL)isMember:(RaveUserReference *) userReference;

Parameters:

userReference - The RaveUserReference object that is to be checked against the group object for membership or role.

Returns: BOOL answer to whether the specified RaveContact is a member of the group.

blockMembers#

Blocks a list of entities /users from joining a group.

- (void)blockMembers:(NSOrderedSet *)users callback:(RaveCompletionCallback)callback;

Parameters:

users - An NSOrderedSet reference containing a list of referenced RaveUserReference objects to be blocked from requesting or being invited to the group.

callback - Callback to call when the blocking is completed

unblockMember#

Unblocks a list of entities from joining a group

- (void)unblockMembers:(NSOrderedSet *)users callback:(RaveCompletionCallback)callback;

Parameters:

users - An NSOrderedSet reference containing a list of referenced RaveUserReference objects to be unblocked from requesting or being invited to the group.

callback - Callback to call when the unblocking is completed

getGroupBlocks#

Lists all entities blocked from joining a group

- (void)getGroupBlocks:(RaveUsersCallback)callback;

Paramters:

callback - A callback that contains the blocked users for a group.

changeMemberRole#

Changes the role membership of a particular group from one role to another.

- (void)changeMemberRole:(RaveGroupMember *)member withRole:(RaveGroupRole)role callback:(RaveCompletionCallback)callback;

Parameters:

member - The RaveGroupMember object representing a user and current membership in the group.

role - An Enum value setting the role a member has in the group

callback - Callback to call when the change is completed

getMember#

returns info about the member, including their role in the group

- (RaveGroupMember *)getMember:(NSString *)uuid

Returns: A RaveGroupMember object which contains basic information about the user contact this membership info represents, and their current tole and memership status in the group.

Gifts API#

Note

In order to use gifts or requests in your application, you must define the gifts that can be given or requested in the Rave Developer Portal. See the Gifts section in the portal documentation for instructions on how to create gifts.

class: RaveGifts

header: <RaveSocial/RaveGifts.h>

giftTypes#

Returns the cached list of gift types:

@property (nonatomic, readonly) NSOrderedSet * giftTypes

Returns: The list of cached gift types for this application

getGiftTypeByName#

Returns a gift type by name:

- (id<RaveGiftType>)getGiftTypeByName:(NSString *)name

Parameters:

name - The name of the gift type

Returns: A gift type or null if no matching

getGiftTypeByKey#

Returns a gift type by key:

- (id<RaveGiftType>)getGiftTypeByKey:(NSString *)typeKey

Parameters:

typeKey - The key of the gift type

Returns: A gift type or null if no matching

updateGiftTypes#

Get the list of gift types for this application:

-(void) updateGiftTypes:(RaveCompletionCallback)callback

Parameters:

callback - Server response callback for gift types

gifts#

Gets a list of the gifts cached for this user:

@property (nonatomic, readonly) NSOrderedSet * gifts

Returns: The list of cached gifts for this user

updateGifts#

Updates the list of gifts from the server:

-(void) updateGifts:(RaveCompletionCallback)callback

Parameters:

callback - Response callback upon completion of the request

sendGiftsWithKeyToUsers#

Sends a gift to multiple users:

-(void) sendGiftsWithKey:(NSString *)giftTypeKey toUsers:(NSArray *)users withCallback:(RaveGiftResultCallback)callback

Parameters:

giftTypeKey - giftTypeKey The key of the gift type to send

user - A list of RaveUsers to send to

callback - result callback

sendGiftsWithKeyToUsersById#

Sends a gift to multiple users:

-(void) sendGiftsWithKey:(NSString *)giftTypeKey toUsersById:(NSArray *)userIds withCallback:(RaveGiftResultCallback)callback

Parameters:

giftTypeKey - giftTypeKey The key of the gift type to send

userIds - A list of RaveIDs to send to

callback - result callback

acceptGift#

Accept a gift:

-(void) acceptGift:(id<RaveGift>)gift withCallback:(RaveCompletionCallback)callback

Parameters:

gift - The gift to accept

callback - Optional result callback to track success or failure of operation

acceptGiftById#

Accept gift by gift ID:

-(void) acceptGiftById:(NSString*)giftId withCallback:(RaveCompletionCallback)callback

Parameters:

giftId - The gift ID for the gift to accept

callback - Optional result callback to track success or failure of operation

rejectGift#

Reject a gift:

-(void) rejectGift:(id<RaveGift>)gift withCallback:(RaveCompletionCallback)callback

Parameters:

gift - The gift to reject

callback - Optional result callback to track success or failure of operation

rejectGiftById#

Reject a gift by gift ID:

-(void) rejectGiftById:(NSString*)giftId withCallback:(RaveCompletionCallback)callback

Parameters:

giftId - The id of the gift to reject

callback - Optional result callback to track success or failure of operation

getGiftRequests#

Returns the list of cached gift requests:

@property (nonatomic, readonly) NSOrderedSet * giftRequests

Returns: The list of cached gift requests

updateGiftRequests#

Updates the local cache of gift requests from the server:

-(void) updateGiftRequests:(RaveCompletionCallback)callback

Parameters:

callback - Response callback upon completion of the request

requestGiftWithKeyFromUsers#

Request a gift from a group of Rave users:

-(void) requestGiftWithKey:(NSString *)giftTypeKey fromUsers:(NSArray *)users withCallback:(RaveGiftResultCallback)callback

Parameters:

giftTypeKey - The key of the gift type being requested

users - The RaveIds of the users targeted by the request

callback - Optional result callback to track success or failure of operation

requestGiftWithKeyFromUsersById#

Request a gift from a group of Rave users:

-(void) requestGiftWithKey:(NSString *)giftTypeKey fromUsersById:(NSArray *)userIds withCallback:(RaveGiftResultCallback)callback

Parameters:

giftTypeKey - The key of the gift type being requested

userIds - The Rave IDs of the users targeted by the request

callback - Optional result callback to track success or failure of operation

grantGiftRequest#

Grant gift request:

-(void) grantGiftRequest:(id<RaveGiftRequest>)request withCallback:(RaveCompletionCallback)callback

Parameters:

request - The gift request to grant

callback - Optional result callback to track success or failure of operation

grantGiftRequestById#

Grant gift request by request id:

-(void) grantGiftRequestById:(NSString*)requestId withCallback:(RaveCompletionCallback)callback

Parameters:

requestId - The request id for the gift request to grant

callback - Optional result callback to track success or failure of operation

ignoreGiftRequest#

Ignore gift request:

-(void) ignoreGiftRequest:(id<RaveGiftRequest>)request withCallback:(RaveCompletionCallback)callback

Parameters:

request - The gift request to ignore

callback - Optional result callback to track success or failure of operation

ignoreGiftRequestById#

Ignore a gift request by request id:

-(void) ignoreGiftRequestById:(NSString*)requestId withCallback:(RaveCompletionCallback)callback

Parameters:

requestId - The uuid of the gift request to ignore

callback - Optional result callback to track success or failure of operation

sendGiftsWithKeyToContacts#

Send a gift to a list of Rave contacts:

-(void) sendGiftsWithKey:(NSString *)giftTypeKey toContacts:(NSArray *)contacts withCallback:(RaveContactGiftResultsCallback)callback

Parameters:

giftTypeKey - The key of the gift type to send

contacts - A list of RaveContacts to send to

callback - Optional result callback to track success or failure of operation

sendGiftsAndShareWithKey toContacts#

Send a gift to a list of Rave contacts and share the gift sent on available social networks:

-(void) sendGiftsAndShareWithKey:(NSString *)giftTypeKey toContacts:(NSArray *)contacts subject:(NSString *)subject message:(NSString *)message withCallback:(RaveGiftAndShareResultsCallback)callback

Parameters:

giftTypeKey - The key of the gift type to send

contacts - A list of RaveContacts to send to

subject - The subject line of the share

message - The message of the share

callback - Optional result callback to track success or failure of operation

sendGiftsAndShareWithKey:viaPlugin:toContacts…#

Send a gift to a list of Rave Contacts and Share the gift sent on available social networks:

-(void) sendGiftsAndShareWithKey:(NSString *)giftTypeKey viaPlugin:(NSString *)pluginKeyName toContacts:(NSArray *)contacts subject:(NSString *)subject message:(NSString *)message withCallback:(RaveGiftAndShareResultsCallback)callback

Parameters:

pluginKeyName - The key name of the sharing plugin to use

giftTypeKey - The key of the gift type to send

contacts - A list of RaveContacts to send to

subject - The subject line of the share

message - The message of the share

callback - Optional result callback to track success or failure of operation

attachGiftWithKey#

Attach a gift to a share request to give the user a gift when they click through the request on the social network:

-(void) attachGiftWithKey:(NSString *)giftTypeKey toShareRequests:(NSArray *)requests withCallback:(RaveCompletionCallback)callback

Parameters:

giftTypeKey - The key of the gift type to attach

requests - The share request to attach the gift to

callback - Optional result callback to track success or failure of operation

fetchGiftKeyForExternalId#

Checks the server to see if there is a gift type queued for the externalId:

-(void) fetchGiftKeyForExternalId:(NSString *)externalId forSource:(NSString *)source withCallback:(RaveGiftKeyCallback)callback

Parameters:

externalId - The external Id (requestId or other)

source - The social network source

callback - The callback with the gift type data

detachGiftKeyForExternalId#

Detaches the queued gift key from the externalId:

-(void) fetchGiftKeyForExternalId:(NSString *)externalId forSource:(NSString *)source withCallback:(RaveGiftKeyCallback)callback

Parameters:

externalId - The external Id (requestId or other)

source - The social network source

callback - The callback with the gift type data

fetchGiftContentForShareInstall#

Fetches the gift type content for a user which has entered the app through a social network share:

- (void)fetchGiftContentForShareInstall:(NSString *)appCallUrl viaPlugin:(NSString *)source withCallback:(RaveGiftContentCallback)callback

Parameters:

appCallUrl - The call URL for the app

source - The social network source

callback - The callback with the gift type content

Leaderboards API#

Note

In order to use leaderboards in your application, you must define your leaderboards in the Rave Developer Portal. See the Leaderboards and Tournaments / Timed Leaderboards section in the portal documentation for instructions on how to create leaderboards.

class: RaveLeaderboards

header: <RaveSocial/RaveLeaderboards.h>

updateLeaderboards#

Updates the list of leaderboards from the server:

- (void)updateLeaderboards:(RaveCompletionCallback)callback

Parameters:

callback - A completion callback

getLeaderboards#

Retrieves the list of leaderboards from cache:

@property (nonatomic, retain, readonly) NSOrderedSet * leaderboards

Returns: A list of RaveLeaderboard objects

updateLeaderboardByKey#

Updates a leaderboard from the server:

- (void)updateLeaderboardByKey:(NSString *)leaderboardKey withCallback:(RaveCompletionCallback)callback

Parameters:

leaderboardKey - The leaderboard key callback - A completion callback

getLeaderboardByKey#

Gets a leaderboard by key:

- (id<RaveLeaderboard>)getLeaderboardByKey:(NSString *)leaderboardkey

Parameters:

leaderboardKey - The key

Returns: A RaveLeaderboard or null if no leaderboard by that name or no leaderboards synced

submitScoreByKey#

Submits a score to a leaderboard:

- (void)submitScoreByKey:(NSString *)leaderboardKey withScore:(NSNumber *)score withCallback:(RaveCompletionCallback)callback

Parameters:

leaderboardKey - The key of the leaderboard score - The score to submit callback - A completion callback

updateGlobalScoresByKey#

Updates a leaderboard’s global scores from the server:

- (void)updateGlobalScoresByKey:(NSString *)leaderboardKey withPage:(NSNumber*)page withPageSize:(NSNumber*)pageSize withCallback:(RaveCompletionCallback)callback

Parameters:

leaderboardKey - The key of the leaderboard to update page - Which page to update pageSize - The size of the page (max 50) callback - A completion callback

getGlobalScoresByKey#

Gets the global scores from local cache:

- (NSOrderedSet *)getGlobalScoresByKey:(NSString *)leaderboardKey withPage:(NSNumber*)page withPageSize:(NSNumber*)pageSize

Parameters:

leaderboardKey - The key of the leaderboard to get for page - Which page to get pageSize - The size of the page (max 50)

Returns: An ordered set of RaveScore objects

updateFriendsScoresByKey#

Updates the user’s friends’ scores for a leaderboard from the server:

- (void)updateFriendsScoresByKey:(NSString *)leaderboardKey withPage:(NSNumber*)page withPageSize:(NSNumber*)pageSize withCallback:(RaveCompletionCallback)callback

Parameters:

leaderboardKey - The key of the leaderboard to update page - Which page to update pageSize - The size of the page (max 50) callback - A completion callback

getFriendsScoresByKey#

Gets the user’s friends’ scores for a leaderboard from local cache:

- (NSOrderedSet*)getFriendsScoresByKey:(NSString *)leaderboardKey withPage:(NSNumber*)page withPageSize:(NSNumber*)pageSize

Parameters:

leaderboardKey - The key of the leaderboard to get for page - Which page to get pageSize - The size of the page (max 50)

Returns: An ordered set of RaveScore objects

updateMyGlobalScoresByKey#

Updates the page of scores which has the user’s current global score for a leaderboard from the server.

- (void)updateMyGlobalScoresByKey:(NSString *)leaderboardKey withPageSize:(NSNumber*)pageSize withCallback:(RaveCompletionCallback)callback

Parameters:

leaderboardKey - The key of the leaderboard to update pageSize - The size of the page (max 50) callback - A completion callback

getMyGlobalScoresByKey#

Gets the page of scores which has the user’s global scores for a leaderboard from local cache

This method returns the page of scores which has the user’s current score.

- (NSOrderedSet*)getMyGlobalScoresByKey:(NSString *)leaderboardKey withPageSize:(NSNumber*)pageSize

Parameters:

leaderboardKey - The key of the leaderboard to get for pageSize - The size of the page (max 50)

Returns: An ordered set of RaveScore objects

updateMyFriendsScoresByKey#

Updates the page of friends’ scores which has the user’s score for a leaderboard from the server.

- (void)updateMyFriendsScoresByKey:(NSString *)leaderboardKey withPageSize:(NSNumber*)pageSize withCallback:(RaveCompletionCallback)callback

Parameters:

leaderboardKey - The key of the leaderboard to update pageSize - The size of the page (max 50) callback - A completion callback

getMyFriendsScoresByKey#

Gets the user’s friends’ scores for a leaderboard from local cache

This method returns the page of friends’ scores which has the user’s current score:

- (NSOrderedSet*)getMyFriendsScoresByKey:(NSString *)leaderboardKey withPageSize:(NSNumber*)pageSize

Parameters:

leaderboardKey - The key of the leaderboard to get for pageSize - The size of the page (max 50)

Returns: An ordered set of RaveScore objects

updateMyGlobalScoresAdjacentByKey#

Updates the user’s global scores with adjacency for a leaderboard from the server.

This method centers the list of scores on the user’s current score.

- (void)updateMyGlobalScoresAdjacentByKey:(NSString *)leaderboardKey withAdjacent:(NSNumber*)adjacent withCallback:(RaveCompletionCallback)callback

Parameters:

leaderboardKey - The key of the leaderboard to update adjacent - The number of adjacent scores (before and after the users score) to show callback - A completion callback

getMyGlobalScoresAdjacentByKey#

Gets the user’s global scores with adjacency for a leaderboard from local cache

This method centers the list of scores on the user’s current score. The list of scores will be up to 2*adjacent+1 in size depending on the user’s position in the list. If the user is in the first or last adjacent number of scores, there will be less results:

- (NSOrderedSet*)getMyGlobalScoresAdjacentByKey:(NSString *)leaderboardKey withAdjacent:(NSNumber*)adjacent

Parameters:

leaderboardKey - The key of the leaderboard to get for adjacent - The number of adjacent scores (before and after the user’s score) to show

Returns: An ordered set of RaveScore objects

updateMyFriendsScoresAdjacentByKey#

Updates the user’s friends’ scores with adjacency for a leaderboard from the server.

This method centers the list of scores on the user’s current score.

- (void)updateMyFriendsScoresAdjacentByKey:(NSString *)leaderboardKey withAdjacent:(NSNumber*)adjacent withCallback:(RaveCompletionCallback)callback

Parameters:

leaderboardKey - The key of the leaderboard to update adjacent - The number of adjacent scores (before and after the user’s score) to show callback - A completion callback

getMyFriendsScoresAdjacentByKey#

Gets the user’s friends’ scores with adjacency for a leaderboard from local cache

This method centers the list of scores on the user’s current score. The list of scores will be up to 2*adjacent+1 in size depending on the user’s position in the list. If the user is in the first or last adjacent number of scores, there will be less results:

- (NSOrderedSet*)getMyFriendsScoresAdjacentByKey:(NSString *)leaderboardKey withAdjacent:(NSNumber*)adjacent

Parameters:

leaderboardKey - The key of the leaderboard to get for adjacent - The number of adjacent scores (before and after the user’s score) to show

Returns: An ordered set of RaveScore objects

getHighScoreByKey#

Gets the current high score for a leaderboard from cache:

- (NSNumber *)getHighScoreByKey:(NSString *)leaderboardKey

Parameters:

leaderboardKey - The key of the leaderboard

Returns: The current high score

getGlobalPositionByKey#

Gets the user’s global position in a leaderboard from cache:

- (NSNumber *)getGlobalPositionByKey:(NSString *)leaderboardKey

Parameters:

leaderboardKey - The key of the leaderboard

Returns: The current global position

getFriendsPositionByKey#

Gets the user’s position amongst friends in a leaderboard from cache:

- (NSNumber *)getFriendsPositionByKey:(NSString *)leaderboardKey

Parameters:

leaderboardKey - The key of the leaderboard

Returns: The current position amongst friends

getLeaderboardScores#

Gets the user’s scores given a request:

- (void)getLeaderboardScores:(RaveLeaderboardsRequest *)request withCallback:(RaveLeaderboardScoresCallback)callback

Parameters:

request - A leaderboard request.

callback - A callback containing the list of scores or an error.

Sharing API#

Users API#

Class: RaveUsersManager#

Main API for accessing and changing Rave users

header: <RaveSocial/RaveUsersManager.h>

convenience class: RaveUsers convenience header: <RaveSocial/RaveUsers.h>

Callback - RaveCompletionCallback#

Completion callback for general use:

typedef void (^RaveCompletionCallback)(NSError * error);

Callback - RaveUserCallback New in 3.3.1*#

Completion callback for returning a user:

typedef void (^RaveUserCallback)(id<RaveUser> user, NSError * error);

Callback - RaveUsersCallback#

Completion callback for returning a list of users:

typedef void (^RaveUsersCallback)(NSOrderedSet * users, NSError * error);

Callback - RaveIdentitiesCallback#

Completion callback for returning a list of merged identities by ID:

typedef void (^RaveIdentitiesCallback)(NSArray * identities, NSError * error);

Callback - RaveAccountExistsListener#

Completion callback for returning whether or not an account exists and has had a password assigned:

typedef void (^RaveAccountExistsCallback)(BOOL accountExists, BOOL hasPassword, NSError * error);

Class: RaveUserChanges - New in 3.0.2#

Create an instance with +[RaveUsersChanges userChanges] method

Use with pushUserChanges to modify the current user by setting any of the following properties:

displayName, realName, email, birthdate, and gender

Protocol: RaveCurrentUserObserver - New in 3.0.2#

Observe changes to the current user

-(void)userChanged:(NSArray *)changedKeys - Publishes an array of keys to fields that changed

Class: RaveUserReference - New in 3.3.1#

Create an instance with +[RaveUserReference byEmail:], +[RaveUserReference byUsername:], or +[RaveUserReference byRaveId:] methods

Use with a variety of methods to refer to a Rave user indirectly

fetchUser - New in 3.3.1#

Find a user by reference, updating the local cache with the user’s data.:

- (void)fetchUser:(RaveUserReference *)reference callback:(RaveUserCallback)callback;

Parameters:

reference - Reference to the user the details for whom should be fetched callback - Callback that will provide the found user or potentially an error

updateCurrent#

Retrieve the current user’s data from the server and update the local cache with the retrieved data.:

- (void)updateCurrent:(RaveCompletionCallback)callback;

Parameters:

callback - Callback to call when the update is completed

current#

Gets the current user stored in the local cache.:

@property (nonatomic, readonly) id<RaveUser> current;

Returns: A RaveUser object representing the current user

fetchBlockedUsers#

Fetch the list of blocked users:

- (void)fetchBlockedUsers:(RaveUsersCallback)callback;

Parameters:

callback - Callback supplying list of users or an error

blockUser#

Block a user:

- (void)blockUser:(RaveUserReference *)reference callback:(RaveCompletionCallback)callback;

Parameters:

reference - Reference to user to be blocked

callback - Callback indicating success of the operation

unblockUser#

Unblock a user:

- (void)unblockUser:(NSString *)raveId callback:(RaveCompletionCallback)callback;

Parameters:

raveId - Rave id for blocked user

callback - Callback indicating success of the operation

addCurrentUserObserver - New in 3.0.2#

Register an observer for the current user, multiple concurrent users may be registered at once:

- (void)addCurrentUserObserver:(id<RaveCurrentUserObserver>)observer;

Parameters:

observer - Observer for changes to the current user

removeCurrentUserObserver - New in 3.0.2#

Unregister an observer for the current user, multiple concurrent users may be registered at once:

- (void)removeCurrentUserObserver:(id<RaveCurrentUserObserver>)observer;

Parameters:

observer - Observer to unregister

pushUserChanges - New in 3.0.2#

Push changes to the current user to the Rave backend. User state notifications will be triggered if successful:

- (void)pushUserChanges:(RaveUserChanges *)userChanges callback:(RaveCompletionCallback)callback;

Parameters:

userChanges - The set of changes to the current user (see RaveUserChanges for more details)

callback - A callback indicating whether or not an error occured

pushProfilePicture - New in 3.0.2#

Push the binary data for a local image to the Rave backend for a user’s profile picture:

- (void)pushProfilePicture:(id)data callback:(RaveCompletionCallback)callback;

Parameters:

data - Data may be of types NSString, NSData, UIImage, or NSURL

callback - A callback indicating whether an error occurred

pushProfilePicture#

Deprecated in 3.0.2 - prefer pushProfilePicture:callback:

Push the binary data for a local image to the Rave backend for a users profile picture:

- (void)pushProfilePicture:(NSString*)url withCallback:(RaveCompletionCallback)callback;

Parameters:

url - The URL specifying the local image to upload

callback - A callback indicating whether or not an error occured

Convenience Function - Ravesocial.currentUser#

Gets the current user stored in the local cache.:

+ (id<RaveUser>)currentUser

Returns: A RaveUser object representing the current user

RaveUser Method - updatePictureImage#

Updates cached profile picture image member pictureImage member based on pictureURL:

- (void)updatePictureImage:(RaveCompletionCallback)callback

Parameters:

callback - Callback to call when the update operation is completed

fetchRandomUsersForApplication#

Fetches a set of random users from the server. Will return up to 10 random users who are using the current application.:

- (void)fetchRandomUsersForApplication:(RaveUsersCallback)callback

Parameters:

callback - Callback to call when the fetch operation is completed. The listener is passed the retrieved data

fetchRandomUsersForApplication#

Fetches a set of random users from the server. Will return up to 10 random users who are using the application specified by the appUuid. The specified application must belong to the same publisher as the current application.:

- (void)fetchRandomUsersForApplication:(NSString *)appUuid callback:(RaveUsersCallback)callback

Parameters:

appUuid - Unique ID of the application whose users you wish to fetch

callback - Callback to call when the fetch operation is completed. The listener is passed the retrieved data

fetchRandomUsersForApplication#

Fetches a set of random users from the server. Will return up to 10 random users who are using the application specified by the appUuid. The specified application must belong to the same publisher as the current application.:

- (void)fetchRandomUsersForApplication:(NSString *)appUuid excludeContacts:(NSNumber *)exludeContacts withLimit:(NSNumber *)limit callback:(RaveUsersCallback)callback

Parameters:

appUuid - Unique ID of the application whose users you wish to fetch

excludeContacts - If the current user’s contacts are included in the results

limit - The maximum number of users to return, up to 25

callback - Callback to call when the fetch operation is completed. The listener is passed the retrieved data

updateUserById#

Given a Rave ID, retrieve a user’s data from the server and update the local cache with the retrieved data.:

- (void)updateUserById:(NSString *)raveId withCallback:(RaveCompletionCallback)callback

Parameters:

raveId - The Rave ID of the user

callback - Callback to call when the update is completed

getUserById#

Gets the current user stored in the local cache.:

- (id<RaveUser>)getUserById:(NSString *)raveId

Parameters:

raveId - The Rave ID of the user

Returns: A RaveUser object representing the retrieved user. Returns null if the user doesn’t exist or isn’t stored in the local cache.

fetchAccessToken#

Fetch an access token that can be used to query the Rave back-end server.:

- (void)fetchAccessToken:(void (^)(NSString * accessToken, NSError * error))callback

Parameters:

callback - Callback to call when the fetch operation is completed. The listener is passed the retrieved data

fetchIdentities#

Fetch all identities associated with the current user. A single user can contain multiple merged identities across games/devices/logins.:

- (void)fetchAllIdentities:(RaveIdentitiesCallback)callback

Parameters:

callback - Callback to call when the fetch operation is completed. The listener is passed the retrieved data

fetchIdentitiesForApplication#

Fetch only identities associated with the current user that are associated with the current application. A single user can contain multiple merged identities across games/devices/logins.:

- (void)fetchIdentitiesForApplication:(RaveIdentitiesCallback)callback

Parameters:

callback - Callback to call when the fetch operation is completed. The listener is passed the retrieved data

checkThirdPartyAccountExists#

Check if the current third party authentication provider contains an account associated with the provided email address.:

- (void)checkThirdPartyAccountExists:(NSString *)email withCallback:(RaveAccountExistsCallback)callback

Parameters:

email - The email address to check against

callback - Callback to call when the check operation is completed. The listener is passed the retrieved data

checkAccountExists#

Check if there is a Rave acccount associated with the provided email address.:

- (void)checkAccountExists:(NSString *)email withCallback:(RaveAccountExistsCallback)callback

Parameters:

email - The email address to check against

callback - Callback to call when the check operation is completed. The listener is passed the retrieved data

blockUser#

Block a user.

- (void)blockUser:(RaveUserReference *)reference withCallback:(RaveCompletionCallback)callback

Parameters:

reference - Reference to the user to block

callback - Completion callback

unblockUser#

Unblock a user.

- (void)unblockUser:(NSString *)raveId callback:(RaveCompletionCallback)callback;

Parameters:

raveId - RaveID of the user to unblock

callback - Completion callback

fetchBlockedUsers#

Fetch the list of blocked users.

- (void)fetchBlockedUsers:(RaveUsersCallback)callback;

Parameters:

callback - Callback supplying the list of users or error

pushCurrent - Deprecated in 3.0.2#

Pushes any changes to the current user stores in the local cache back to the server.:

- (void)pushCurrent:(RaveCompletionCallback)callback;

Parameters:

callback - Callback to call when the push operation is completed

RaveUser Method - setPictureImage - Deprecated in 3.0.2#

Sets the profile picture for RaveUser object.:

- (void)setPictureImage:(UIImage *)pictureImage

Parameters:

pictureImage - A UIImage of the new profile picture

Authentication API#

class: RaveAuthentication

header: <RaveSocial/RaveAuthentication.h>

Callback - RaveConnectStateCallback#

Callback for plugin connect state:

typedef void (^RaveConnectStateCallback)(BOOL isConnected, String userId, NSError * error)

Parameters:

isConnected - YES or NO given whether plugin is connected with Rave

userId - User id of user for social provider (e.g. FB UID)

error - Error if any was encountered or nil

Callback - RaveReadinessCallback#

Callback for plugin readiness state:

typedef void (^RaveReadinessCallback)(BOOL isReady, NSError * error)

Parameters:

isReady - YES or NO given whether plugin is ready (e.g. connected and userId equals expected UID associated with Rave account)

error - Error if any was encountered or nil

Class RaveAuthentication#

connectPlugins#

Gets all registered plugins:

- (NSArray *)connectPlugins

Returns: A container of the registered plugins

getConnectPlugin#

Returns a connect plugin instance referred to by pluginKeyName:

- (id)getConnectPlugin:(NSString *)pluginKeyName

Parameters:

pluginKeyName - The pluginKeyName key for the plugin used when registering Returns: The plugin registered with the system or nil

registerConnectPlugin#

Register a connect plugin object, it will assume the pluginKey as key:

- (void)registerConnectPlugin:(id<RaveConnectPlugin>)plugin

Parameters:

plugin - The connect plugin to register with the manager

registerConnectPluginByName#

Register a built-in connect plugin by registration name:

- (void)registerConnectPluginByName:(NSString *)pluginKeyName

Parameters:

pluginKeyName - The name of the built-in plugin to register, e.g. “facebook”

loginAsGuest#

Log in to Rave as Guest (Anonymous):

- (void)loginAsGuest:(RaveCompletionCallback)callback;

Parameters:

callback - Completion callback for operations success

loginWith#

Attention

Rather than implementing a fully custom control for connecting your users we suggest as best practice that you instead use your custom UI to wrap one of our connect controllers. Please read Adding a Facebook (or another social provider) button to your App.

Logs in using an authentication provider

- (void)loginWith:(NSString *)pluginKeyName callback:(RaveCompletionCallback)callback;

Parameters:

pluginKeyName - The KeyName of the authentication provider plugin callback - A completion callback or nil if no notification is desired

connectTo#

Attention

Rather than implementing a fully custom control for connecting your users we suggest as best practice that you instead use your custom UI to wrap one of our connect controllers. Please read Adding a Facebook (or another social provider) button to your App.

Connects an existing Rave account using an authentication provider

- (void)connectTo:(NSString *)pluginKeyName callback:(RaveCompletionCallback)callback;

Parameters:

pluginKeyName - The KeyName of the authentication provider plugin callback - A completion callback or nil if no notification is desired

forceConnectTo#

Connects an existing Rave account using an authentication provider:

- (void)forceConnectTo:(NSString *)pluginKeyName callback:(RaveCompletionCallback)callback;

Parameters:

pluginKeyName - The KeyName of the authentication provider plugin callback - A completion callback or nil if no notification is desired

disconnectFrom#

Disconnect an existing account from an authentication provider:

- (void)disconnectFrom:(NSString *)pluginKeyName callback:(RaveCompletionCallback)callback;

Parameters:

pluginKeyName - The KeyName of the authentication provider plugin callback - A disconnect callback or nil if no notification is desired

lastKnownReadinessOf#

Gets the last known readiness state of an authentication provider

- (BOOL)lastKnownReadinessOf:(NSString *)pluginKeyName;

Parameters:

pluginKeyName - The KeyName of the authentication provider plugin

Returns: YES if the plugin is ready, otherwise NO

checkReadinessOf#

Checks the current readiness state of an authentication provider

- (void)checkReadinessOf:(NSString *)pluginKeyName callback:(RaveReadinessCallback)callback;

Parameters:

pluginKeyName - The KeyName of the authentication provider plugin callback - A readiness callback, or nil if no notification is desired

getCurrentTokenFrom#

Gets the current token of a specific type from an authentication provider

- (NSString *)getCurrentTokenFrom:(NSString *)pluginKeyName;

Parameters:

pluginKeyName - The KeyName of the authentication provider plugin

Returns: The current access token or nil

getCurrentTokenFrom#

Gets the current access token from an authentication provider

- (NSString *)getCurrentTokenFrom:(NSString *)pluginKeyName tokenType:(RaveConnectPluginTokenType)tokenType;

Parameters:

pluginKeyName - The KeyName of the authentication provider plugin tokenType - The token type to get (e.g. access token or token secret)

Returns: The requested token or nil

fetchConnectStateOf#

Fetches the current connect state of an authentication provider

- (void)fetchConnectStateOf:(NSString *)pluginKeyName callback:(RaveConnectStateCallback)callback;

Parameters:

pluginKeyName - The KeyName of the authentication provider plugin callback - A connect state callback or nil if no notification is desired

logOut#

Log out of the current Rave account clearing all cached tokens in plugins. If RaveSettings.General.AutoGuestLogin is enabled an anonymous guest user will automatically be created

Providing a null callback will result in operations such as automatic guest login and session deletion happening asynchronously. To guarantee that a race does not happen with any other authentication actions, it is highly recommended that a listener be set and that no other Rave APIs be called until the listener has called back.

- (void)logOut:(RaveCompletionCallback) callback;

useTokenForRaveUpgradeWith#

A method to explicitly set a token for a plugin to use to connect to Rave This method is typically used if a token has been acquired in an app prior to integrating Rave. Usually after that point the token should be cleared as you won’t need to upgrade again. In addition if you use the normal method of token storage for the given plugin this method doesn’t need to be called at all.

- (void)useTokenForRaveUpgradeWith:(NSString *)pluginKeyName token:(NSString *)token;

Parameters:

pluginKeyName - The KeyName of the authentication provider plugin token - The token to give to Rave for automatic authentication attempts

fetchThirdPartyInfo#

Fetches third party info:

- (void)fetchThirdPartyInfo:(NSString *)pluginKeyName callback:(RaveConnectStateCallback)callback;

Parameters:

pluginKeyName - The KeyName of the authentication provider plugin callback - A connect state callback

Contents