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.

public delegate void RaveAppDataKeysStateObserver(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.cs included in your distribution package.

Accessing the current user

RaveUsersManager.CurrentUser 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(List<string>).

void UserChanged(List<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.

Unity provides access to the image URL through RaveUsersManager.CurrentUser.pictureURL

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.

RaveUsersManager.PushProfilePicture(imageURL,delegate(string error) {
   if(error != "") {
       // 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, RaveCompletionCallback callback).

RaveUserChanges changes = new RaveUserChanges();
    changes.displayName = someOtherName;
    RaveUsersManager.PushUserChanges(changes, delegate(string 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 you log out. Prior to the logOut completion callback firing it is suggested that you prevent the user from interacting with Rave.

RaveSocial.LogOut(delegate(string error) {
    if (error != "") {
        // do something to handle the error
    }
});

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 = new RaveConnectFriendsController(RaveConstants.CONNECT_PLUGIN_FACEBOOK);
    controller.SetObserver(delegate(RaveConnectFriendsControllerState state) {
    // ... see details below
    });

    // Only necessary if you want to filter and display error messages
    controller.SetCallback(delegate(string error) {
    if (error != "") {
        // do something to handle the error
    }
});

Tracking current state:

SetObserver(delegate(RaveConnectFriendsControllerState state) {
    // You will also want to update your UI to reflect the state
    switch (value) {
        case RaveFriendsControllerStateNotDownloaded:
            downloaded = false;
            break;
        case RaveFriendsControllerStateDownloading:
            // do something to indicate busy
            break;
        case RaveFriendsControllerStateDownloaded:
            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(delegate(string error) {
        //      do something
});

Tracking current state:

SetObserver(delegate(RaveConnectControllerState value) {
        switch (value) {
        case RaveConnectControllerStateDisabled:
                //      disable UI
                break;
        case RaveConnectControllerStateConnected:
                connected = YES;
                break;
        case RaveConnectControllerStateConnecting:
        //  do something to indicate busy
                break;
        case RaveConnectControllerStateDisconnected:
                connected = NO;
                break;
        case RaveConnectControllerStateDisconnecting:
        //  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.

RaveSocial.ShowLoginScene(delegate(RaveCallbackResult result, BigFishSignUpData signUpData, string error) {
if(result == RaveCallbackResult.RaveResultSuccessful && signUpData != null) {
        // do something
} else if(result == RaveCallbackResult.RaveResultCanceled) {
        // do something else
} else {
        // show error message if deemed appropriate
}
});

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.

RaveSocial.ShowSignUpEmailScene(delegate(RaveCallbackResult result, BigFishSignUpData signUpData, string error) {
if(result == RaveCallbackResult.RaveResultSuccessful && signUpData != null) {
        // do something
} else if(result == RaveCallbackResult.RaveResultCanceled) {
        // do something else
} else {
        // show error message if deemed appropriate
}
});

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.

RaveSocial.ShowFindFriendsScene(delegate(string error) {
// capture when this scene is closed if desired
});