Player Login Experience#

The default login flow allows players to access their Big Fish gamer account or create a new one using the following methods:

  • Email — sign in with an email address associated with player’s Big Fish ID account

  • Facebook — log in or create a new account using Facebook credentials

  • Google (Android only) — log in or create a new account using Google credentials

  • Apple (iOS only) — log in or create a new account using Apple credentials

Note

As of BigFishScenePack version 4.5.0, creating a new account via Email is no longer supported. Email can only be used to sign in to an existing Big Fish ID.

../_images/player_login_experience1.png

In order to integrate this scene it’s important that the Facebook and Google apps used in the Rave integration are properly configured. Please see Integrating Third Party Authentication section for instructions on how to configure the social networks apps.

The Newsletter Opt-In callback may be triggered automatically as part of the login flow (e.g. if the user logged in via Facebook or Google and shared their email). See the Newsletter Opt-In Flow section for full details.

To integrate the login experience:

RaveAuthHomeScene authHomeScene = new RaveAuthHomeScene(activity);
authHomeScene.setSceneCompleteListener(new BigFishSceneCompleteListener() {
    @Override
    public void onSceneComplete(RaveCallbackResult result, RaveException exception) {
        if (result == RaveCallbackResult.RESULT_ERROR) {
          // handle error
        } else if (result == RaveCallbackResult.RESULT_CANCELED) {
          // handle canceled
        } else if (result == RaveCallbackResult.RESULT_SUCCESSFUL) {
          // handle successful
        }
    }
});
authHomeScene.show();

Registering and Handling Login Callbacks#

RaveSocial provides key Scene and Login status callbacks that a developer can register and listen to.

Login Status Notification#

The general Login Callback (not to be confused with the RaveLoginScene callback, which is specific to Scene-based authentication flows) is used to notify the developer that a login status change of some kind has occurred. This is useful because it may indicate that some social features are now available.

Warning

  • In 4.3.0, the login listener triggers twice during SDK initialization. See Impact on Login Listener Behavior.

  • In 4.3.1, the login listener triggers once during SDK initialization, restoring the behavior prior to SDK 4.3.0. See Restoration of Login Status Listener Behavior.

  • The deprecated RaveLoginStatus values ERROR and NONE are no longer used and will be removed in a future version.

  • The exception parameter in onLoginStatusChanged is now always null and should be ignored. It will be removed in a future version.

RaveSocial.setLoginListener(new RaveLoginStatusListener() {
  @Override
  public void onLoginStatusChanged(@NonNull RaveLoginStatus status, @Nullable @Deprecated RaveException ignored) {
    if (RaveSocial.isLoggedInAsGuest()) {
      //handle guest access here
    }
    //post-login code here
  }
});

Directly Logging In to Authentication Providers#

If using the built-in Big Fish Login experiences is not desired, developer can build completely custom login experience using Rave’s login APIs.

Using our loginWith API, you can directly invoke a login via Facebook or Google. Please use the following constants:

  • Facebook

  • Google

RaveSocial.loginWith("Facebook", new RaveCompletionListener() {
  @Override
  public void onComplete(RaveException exception) {
        if (exception != null) {
            // handle error
        } else {
                            // success
        }
  }
});

Checking Readiness of Authentication Providers#

Just like with the direct login API - you can also see if an authentication provider is ready to be used. “Readiness” indicates that a user has connected this social account to their Rave Social account and also that the token or local authentication for this social account was successful. Call convenience functions in RaveSocial to check a plugin’s readiness. If a plugin is not ready but you desire a ready status, use the matching connect methods in RaveSocial to establish a connection with the the desired plugin.

RaveSocial.checkReadinessOf("Facebook", new RaveReadinessListener() {
  @Override
  public void onComplete(RaveReadyStatus status) {
    //handle result
  }
});

RaveSocial.connectTo("Facebook", new RaveCompletionListener() {
  @Override
  public void onComplete(RaveException exception) {
    if (exception) {
      // handle error
    } else {
      // success
    }
  }
});

Player Profile Management Experience#

The profile management experience screen allows players to build out their game profile by adding a profile picture, email, and display name, as well as connecting various social networks to connect with friends.

This screen will also have a link to login or sign-up if the user hasn’t done so already.

To integrate the Profile Management experience:

RaveAccountInfoScene accountInfoScene = new RaveAccountInfoScene(BigFishDemoStartActivity.this);
accountInfoScene.setSceneCompleteListener(new BigFishSceneCompleteListener() {
  @Override
  public void onSceneComplete(RaveCallbackResult result, RaveException exception) {
      // handle any login or sign-up actions here
});
accountInfoScene.show();

Find Friends Experience#

The Find Friends screen allows the player to connect their Facebook and Google accounts, and their local Phonebook to find friends who are also playing Big Fish games.

As the player connects his social network account to his gamer account, Rave will keep track of which of player’s friends are also playing Big Fish games and will add those friends to the list of player’s gamer contacts. These friends will be available in games for in-game interactions such as sending gifts to them and for social leaderboards.

../_images/find_friends_experience.png

To integrate the Find Friends experience:

FindFriendsScene scene = new FindFriendsScene(BigFishDemoStartActivity.this);
if( FindFriendsScene.shouldShow() ) {
  scene.show();
} else {
  // ends up here if all plugins are already connected and it is not necessary to show the scene
}

Newsletter Opt-In Flow#

The Newsletter Opt-In Scene allows authenticated users that shared their emails to opt in or out of receiving marketing communications.

It can be shown either automatically during login or manually after login. When the user responds, their decision is returned through a callback. You are responsible for handling that callback and submitting the choice to your backend.

The newsletter name used for opt-in can be configured via the setting: BigFishSettings.General.NewsletterName.

Integration options#

There are two ways to integrate the newsletter scene:

1. Automatic display after login#

If you’re using the default Rave login flow via RaveAuthHomeScene or RaveLoginScene, the newsletter opt-in scene will be shown automatically if:

  • The user is authenticated via Facebook, Google, or Apple

  • The user has shared a valid email address

You can handle the result by setting a listener:

RaveAuthHomeScene authHomeScene = new RaveAuthHomeScene(this);
authHomeScene.setNewsletterOptInListener(optedIn -> {
    BigFishScenePack.submitNewsletterOptInStatus(optedIn);
});

Note

If you want to disable the automatic display of the Newsletter Opt-In scene, you can do so by setting: BigFishSettings.UI.ShowNewsletterOptInPostLogin to false.

This setting is available starting in BigFishScenePack version 4.5.2.

Important

Previously, the newsletter scene made the SUSI newsletter subscription API call internally.

As of BigFishScenePack version 4.5.0, this call must be handled by the app using the provided opt-in callback.

For convenience, a helper method was added to mimic the previous behavior:

BigFishScenePack.submitNewsletterOptInStatus(optedIn);

2. Manual trigger after login (Standalone version)#

You may also manually present the scene at any time post-login, for example from a settings screen or onboarding flow.

Use the utility method from BigFishScenePack:

BigFishScenePack.showNewsletterOptInScene(this, optedIn -> {
    // Handle opt-in value here (true or false)
    BigFishScenePack.submitNewsletterOptInStatus(optedIn);
});

Callback reference#

The scene returns the result via the following interface:

public interface BigFishNewsletterOptInListener {
    /**
     * Called when the user completes the Newsletter Opt-In scene.
     *
     * @param optedIn True if the user opted in, false otherwise.
     *                Dismissal or back press is treated as opt-out.
     */
    void onNewsletterChoice(boolean optedIn);
}

This callback will be invoked regardless of whether the user opts in, opts out, or dismisses the scene (dismissal is treated as opt-out).