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 RaveID was used in the past, then RaveAppDataKeys is the recommended API to use. Simply implement the protocol RaveAppDataKeysStateObserver.

public static void appDataKeyStateChanged(String selectedKey, List<String> 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() (see selectKey for more information).

User Profile Scenarios

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

Accessing the current user

RaveSocial.getCurrentUser() is a shortcut method for accessing the current user.

Provided RaveSettings.General.AutoGuestLogin is enabled this value should never be null, even after a log out operation. You can access a variety of fields to populate your 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 the an array of the changed properties of the current user.

It is recommended that you leverage this feature in your custom profile scene for displayName and pictureURL (or pictureImage) since they 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 interface, which consists of one method: RaveCurrentUserObserver.userChanged(Collection<String>).

@Override
void userChanged(Collection<String> changedKeys) {
    if (changedKeys.contains("displayName")) {
        //  Update UI with new display name
    } else if (changedKeys.contains("pictureImage")) {
        //  Update UI with new profile picture
    } else if (changedKeys.contains("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.

Android provides access to the image URL through RaveSocial.getCurrentUser().getPictureURL()

Changing the 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.

String imageURL = someLocalImageURL;
RaveSocial.usersManager.pushProfilePicture(imageURL, new RaveCompletionListener() {
   @Override
    public void onComplete(RaveException exception) {
        if (exception) {
          // do something in the error case
        }
    }
});

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(RaveUserChanges changes, RaveCompletionListener listener).

RaveUserChanges changes = new RaveUserChanges();
changes.displayName = someOtherName;
RaveSocial.usersManager.pushUserChanges(changes, new RaveCompletionListener() {
    @Override
    public void onComplete(RaveException exception) {
        if (exception) {
            // do something to handle the exception
        }
    }
});

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 you log out. Prior to the logOut completion listener firing it is suggested that you prevent the user from interacting with Rave similar to what is shown in the snippet below.

RaveSocial.getProgressDisplay().show("Signing out...", null);
RaveSocial.logOut(new RaveCompletionListener() {
    @Override
    public void onComplete(RaveException exception) {
        RaveSocial.getProgressDisplay().dismiss();
        if (exception) {
            // do something to handle the exception
        }
    }
});

Finding friends via Facebook (or other social provider)

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.

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 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 opportunistically with a configurable time interval. For an overview of app contacts features, see: Contacts

Creating a controller:

RaveConnectFriendsController controller = new RaveConnectFriendsController(RaveConstants.CONNECT_PLUGIN_FACEBOOK);
controller.setFriendsObserver(new RaveConnectFriendsStateObserver() {
    //  ... see details below
});

// Only necessary if you want to filter and display error messages
controller.setCallback(new RaveCompletionListener() {
    @Override
    public void onComplete(RaveException exception) {
        if (exception) {
            // do something to handle the exception
        }
    }
});

Tracking current state:

@Override
void onFindFriendsStateChanged(RaveFindFriendsState value) {
    // You will also want to update your UI to reflect the state
    switch (value) {
    case FIND_FRIENDS_STATE_NOT_DOWNLOADED:
        downloaded = false;
        break;
    case FIND_FRIENDS_STATE_DOWNLOADING:
        //  do something to indicate busy
        break;
    case FIND_FRIENDS_STATE_DOWNLOADED:
        downloaded = true;
        break;
    }
}

Toggling state:

if (downloaded) {
    controller.attemptForgetFriends();
} else {
    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 =  new RaveConnectController(RaveConstants.CONNECT_PLUGIN_FACEBOOK);
controller.setObserver(...); // See details below

// Only necessary if you want to filter and display error messages
controller.setCallback(new RaveCompletionListener() {
    @Override
    public void onComplete(RaveException exception) {
        if (exception) {
            // do something to handle the exception
        }
    }
});

Tracking current state:

@Override
void onConnectStateChanged(RaveConnectControllerState value) {
        switch (value) {
        case CONNECT_STATE_DISABLED:
                //      disable UI
                break;
        case CONNECT_STATE_CONNECTED:
                connected = YES;
                break;
        case CONNECT_STATE_CONNECTING:
        //  do something to indicate busy
                break;
        case CONNECT_STATE_DISCONNECTED:
                connected = NO;
                break;
        case CONNECT_STATE_DISCONNECTING:
        //  do something to indicate busy
                break;
        }
}

Toggling state:

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

Opening common scenes

Opening the login scene

Opening the login scene allows the user to sign in using their BigFish account. It also provides the user with a convenient shortcut to the create account 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.

RaveLoginScene loginScene = new RaveLoginScene(context);
loginScene.setListener(new BigFishSignUpDataListener() {
        @Override
        public void onComplete(RaveCallbackResult result, BigFishSignUpData signUpData, RaveException exception) {
        if (result == RESULT_SUCCESSFUL && signUpData != null) {
                //  do something
        } else if (result == RESULT_CANCELED) {
                //  do something else
        } else {
                //  show error message if deemed appropriate
        }
});
loginScene.show();

Opening the create account scene

Opening the sign up email 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 = new RaveSignUpEmailScene(context);
signUpScene.setListener(new BigFishSignUpDataListener() {
@Override
public void onComplete(RaveCallbackResult result, BigFishSignUpData signUpData, RaveException exception) {
        if (result == RESULT_SUCCESSFUL && signUpData != null) {
        // do something?
        } else if (result == RESULT_CANCELED) {
        // do something else?
        } else {
        // show error message if deemed appropriate
        }
}
});
signUpScene.show();

Opening the Find Friends scene

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 = new RaveFindFriendsScene(context);
findFriendsScene.setListener(new RaveSceneListener() {
@Override
public void onSceneComplate(boolean cancelled, RaveException exception) {
        // capture when this scene is closed if desired
}
});