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];