com.captainup.android.framework

Class CaptainUp

java.lang.Object

com.captainup.android.framework.CaptainUp

public final class CaptainUp
extends java.lang.Object

The main class to access the Captain Up Framework. To work with this class, always maintain the following workflow:

1. Use addListener(CaptainUpListener) with ConnectionCaptainUpListener and AuthenticateCaptainUpListener
2. Call connect(Context, int)
3. After receiving ConnectionCaptainUpListener.onAfterConnect(Application), authenticate you App's user with captain up, using authenticate(IntegrationUser)
4. Even before the authentication is complete, you can now query the application and its leaderboards
5. After receiving AuthenticateCaptainUpListener.onAuthenticationDone(ActionableUser) you can get the logged in user, perform action on it, and listen to its events

Method Summary

Modifier and Type	Method and Description
static void	addListener(CaptainUpListener listener) Adds a listener to Captain Up events.
static void	authenticate(android.content.Context context, int configId, IntegrationUser user) Connects and Authenticates a user to Captain Up.
static void	authenticate(IntegrationUser user) Authenticates a user to Captain Up.
static void	connect(android.content.Context context, int configId) Initializes Captain Up objects.
static void	disconnect() Disconnect from Captain Up.
static Application	getApplication() Returns all the current connected application's settings, including information on the action settings, levels, badges and etc.
static android.content.Context	getContext()
static ActionableUser	getLoggedInUser() Returns the logged in user.
static CaptainUpProperties	getProperties() Get the Captain Up properties
static java.util.Map<java.lang.String,Badge>	getSegmentedBadges()
static void	getUser(java.lang.String userId, CaptainUpCallback<User> callback)
static boolean	isAuthenticated() Checks whether or not you already authenticated a user with the Captain Up SDK.
static boolean	isConnected() Checks whether or not you are already connected to Captain Up.
static void	queryLeaderboard(LeaderboardTime time, java.lang.String playerId, Query query, CaptainUpCallback<LeaderboardCaptainUpResponse> callback)
static void	querySocialFeed(CaptainUpCallback<GetSocialFeedCaptainUpResponse> callback)
static void	refresh() Refreshes the Captain Up connection and logged in user (if any).
static void	removeListener(CaptainUpListener listener) Removes a listener from this user instance.
static void	SetLanguageCode(java.lang.String languageCode) Sets the application language, use this function to set your user localization.

Methods inherited from class java.lang.Object

clone, equals, finalize, getClass, hashCode, notify, notifyAll, toString, wait, wait, wait

Method Detail

addListener

public static void addListener(CaptainUpListener listener)

Adds a listener to Captain Up events. The type of event or events being listened to is determined by the interfaces implemented by the listener parameter. Supported events:

• Connection Established - ConnectionCaptainUpListener
• User Authenticated - AuthenticateCaptainUpListener

Parameters:

listener - any object implementing CaptainUpListener. The listener can implement multiple interfaces and thus will be registered to all events it supports.

removeListener

public static void removeListener(CaptainUpListener listener)

Removes a listener from this user instance.

Parameters:

listener - the listener object to be removed.

isConnected

public static boolean isConnected()

Checks whether or not you are already connected to Captain Up.

Returns:

true if and only if you are already connected to Captain Up.

See Also:

connect(Context, int)

connect

public static void connect(android.content.Context context,
                           int configId)
                    throws ConfigFileCaptainUpException

Initializes Captain Up objects. This must be called before any other methods (such as authenticate(IntegrationUser)). If the connection succeeds and there's a ConnectionCaptainUpListener registered, the onAfterConnect will be called. If there was an error connection, and there's a ErrorCaptainUpListener registered, the onError will be called. Make sure you call addListener(CaptainUpListener) before connect. For most cases, there's no need to distinguish between the "connect" and "authenticate" flows. Consider using authenticate(Context, int, IntegrationUser) instead.

Parameters:

context - your app's context

configId - the id of the captain up configuration. By default use R.raw.captainup_config.

Throws:

ConfigFileCaptainUpException - thrown if there's an error reading the configuration file

java.lang.IllegalStateException - thrown if you tried calling connect after a previous successful call to connect

See Also:

authenticate(Context, int, IntegrationUser)

disconnect

public static void disconnect()

Disconnect from Captain Up. Can be used to log in a new user. To log in with a new user (when already logged in), call disconnect and than authenticate(Context, int, IntegrationUser) with your new user id. Remember to add listeners

authenticate

public static void authenticate(IntegrationUser user)

Authenticates a user to Captain Up. If the user does not exist in Captain Up yet, it will be created. In any case, if the authentication was successful and there is a AuthenticateCaptainUpListener registered, the onAuthenticationDone will be called. If there was an error connection, and there's a ErrorCaptainUpListener registered, the onError will be called. Must be called after a successful call to connect(Context, int).

If the Captain Up Configuration files define a non-empty "login_action", that action will be automatically invoked by the framework.

The Framework supports only one logged in user. If you require more than that, use the "Core" objects (i.e. CaptainUpConnection.authenticate(User)).

Parameters:

user - the user to authenticate and log in.

Throws:

java.lang.IllegalStateException - thrown if trying to authenticate before a call to connect(Context, int)

See Also:

authenticate(Context, int, IntegrationUser)

authenticate

public static void authenticate(android.content.Context context,
                                int configId,
                                IntegrationUser user)

Connects and Authenticates a user to Captain Up. If the connection succeeds and there's a ConnectionCaptainUpListener registered, the onAfterConnect will be called. If the user does not exist in Captain Up yet, it will be created. In any case, if the authentication was successful and there is a AuthenticateCaptainUpListener registered, the onAuthenticationDone will be called. If there was an error connection, and there's a ErrorCaptainUpListener registered, the onError will be called. Make sure you call addListener(CaptainUpListener) before connect.

If the Captain Up Configuration files define a non-empty "login_action", that action will be automatically invoked by the framework.

The Framework supports only one logged in user. If you require more than that, use the "Core" objects (i.e. CaptainUpConnection.authenticate(User)).

Parameters:

context - your app's context

configId - the id of the captain up configuration. By default use R.raw.captainup_config.

user - the user to authenticate and log in.

isAuthenticated

public static boolean isAuthenticated()

Checks whether or not you already authenticated a user with the Captain Up SDK.

Returns:

true if and only if you successfully authenticated a user.

See Also:

authenticate(IntegrationUser)

queryLeaderboard

public static void queryLeaderboard(LeaderboardTime time,
                                    java.lang.String playerId,
                                    Query query,
                                    CaptainUpCallback<LeaderboardCaptainUpResponse> callback)

querySocialFeed

public static void querySocialFeed(CaptainUpCallback<GetSocialFeedCaptainUpResponse> callback)

getApplication

public static Application getApplication()

Returns all the current connected application's settings, including information on the action settings, levels, badges and etc. The call to connect(Context, int) must have completed successfully before calling this method.

Returns:

the application that was connected to.

Throws:

java.lang.IllegalStateException - thrown when the called before connect(Context, int) or if it failed

getUser

public static void getUser(java.lang.String userId,
                           CaptainUpCallback<User> callback)

getLoggedInUser

public static ActionableUser getLoggedInUser()

Returns the logged in user. If there is not a yet a logged in user, a user object will still be returned. This "empty user" will not contain any information about the user (such as his\her name or ID), but it still allows the developer to start listening for events and perform actions. Once you successfully authenticated a user, any pending actions will be sent and processed and any events will be raised accordingly. Note: if the was a disconnect (for exmaple, the client's network is down), after a successful connection, the user will contain the latest information we've got. Any actions performed while in this "disconnect" state will generate errors (ErrorCaptainUpUserListener). It is your responsibility to aggregate these failed actions and they will not be retried.

Returns:

the logged in user.

refresh

public static void refresh()

Refreshes the Captain Up connection and logged in user (if any). If there was a logged in user, then the user's information will be updated within the same ActionableUser instance. Any listeners connected to the user will be invoked to reflect changed because of the update. This is an asynchronous operation that will trigger listeners. Once the refresh is done the AuthenticateCaptainUpListener will be invoked.

getContext

public static android.content.Context getContext()

getProperties

public static CaptainUpProperties getProperties()

Get the Captain Up properties

Returns:

null if Captain Up is not initialized

SetLanguageCode

public static void SetLanguageCode(java.lang.String languageCode)

Sets the application language, use this function to set your user localization. Localization will affect all badges and levels names and description. This function must be called before calling @see authenticate(Context context, int configId, final IntegrationUser user) or @see connect(Context context, int configId)

Parameters:

languageCode - the user language code

getSegmentedBadges

public static java.util.Map<java.lang.String,Badge> getSegmentedBadges()