This project is a part of The SOOMLA Framework, which is a series of open source initiatives with a joint goal to help mobile game developers do more together. SOOMLA encourages better game design, economy modeling, social engagement, and faster development.
The gist:
//The example below uses Facebook provider, to use different provider change IProvider.Provider.FACEBOOK
//to IProvider.Provider.Twitter or IProvider.Provider.GooglePlus
// decide on rewards (here 1 "sword" virtual item) for social action
Reward reward = new VirtualItemReward([id], "Update Status for item", 1, "sword");
// optional reward on each action, select from available social providers
SoomlaProfile.getInstance().login([activity], IProvider.Provider.FACEBOOK, [reward]);
// after login, the user profile on the selected providers is available locally
UserProfile userProfile = SoomlaProfile.getInstance().getStoredUserProfile();
// on successful login event, you can perform actions on the provider
// this will post to Facebook, upon completion, the user will get 1 sword!
SoomlaProfile.getInstance().updateStatus(IProvider.Provider.FACEBOOK, "cool game!", reward);
November 16th: v1.0 android-profile supports Facebook, Google+ and Twitter
android-profile is an open code initiative as part of The SOOMLA Project. It is a Java API that unifies interaction with social and identity provider APIs, and optionally ties it together with the game's virtual economy. This enables to easily reward players with social actions they perform in-game, and to leverage user profiles.
git clone --recursive https://github.com/soomla/android-profile.git
./build_all
from project directorybuild
directory and use it!From the downloaded zip, Add the following jars to your project.
SoomlaAndroidCore.jar
AndroidProfile.jar
square-otto-1.3.2.jar
Make the following changes to your AndroidManifest.xml:
Set SoomlaApp
as the main Application by placing it in the application
tag:
<application ...
android:name="com.soomla.SoomlaApp">
Initialize Soomla
with a secret that you chose to encrypt the user data. (For those who came from older versions, this should be the same as the old "custom secret"):
Soomla.initialize("[YOUR CUSTOM GAME SECRET HERE]");
The secret is your encryption secret for data saved in the DB.
Initialize SoomlaProfile
SoomlaProfile.getInstance().initialize();
Note that some social providers need special parameters in intialization, you can supply them like so:
HashMap<IProvider.Provider, HashMap<String, String>> providerParams = new
HashMap<IProvider.Provider, HashMap<String, String>>();
// Fill in the HashMap according to social providers
SoomlaProfile.getInstance().initialize(providerParams);
HashMap<String, String> facebookParams = new HashMap<String, String>();
facebookParams.put("permissions", "public_profile,user_friends");
providerParams.put(IProvider.Provider.FACEBOOK, facebookParams);
SoomlaProfile.getInstance().initialize(providerParams);
NOTE: You should not request all the possible permissions you'll ever need in your app, just request the reasonable minimum. Other permissions will be requested, when they will be needed. For instance, if you try to call
updateStatus
, SoomlaProfile will ask forpublish_actions
permission, if your app has not got it.
Twitter - Please provide Consumer Key and Consumer Secret from the "Keys and Access Tokens" section in Twitter Apps, like so:
HashMap<String, String> twitterParams = new HashMap<String, String>();
twitterParams.put("consumerKey", "[YOUR CONSUMER KEY]");
twitterParams.put("consumerSecret", "[YOUR CONSUMER SECRET]");
providerParams.put(IProvider.Provider.TWITTER, twitterParams);
If integrating a virtual economy with the store module, please see android-store for store setup.
Refer to the next section for information of selecting social providers and setting them up.
Cool, almost there, on to provider selection!
android-profile is structured to support multiple social networks (Facebook, Twitter, etc.), at the time of writing this the framework only supports Facebook integration. We use the Simple Facebook project to support this integration.
Facebook is supported out-of-the-box, you just have to follow the next steps to make it work:
From the downloaded zip, Add the following jars to your project.
AndroidProfileFacebook.jar
simple-fb-4.0.3.jar
gson-1.7.2.jar
Import the Facebook SDK for Android into your project and setup all the relevant information (Application ID, etc).
For more information regarding this refer to Facebook SDK for Android
SOOMLA uses Android Studio, in this case you can extract the Facebook SDK into your project folder and then it's simply a case of importing the iml
file in the Facebook SDK folder into your project
Make the following changes in AndroidManifest.xml
:
...
<application ...
<activity android:name="com.soomla.profile.social.facebook.SoomlaFacebook$SoomlaFBActivity" android:theme="@android:style/Theme.Translucent.NoTitleBar.Fullscreen">
</activity>
</application>
Twitter is also supported out-of-the-box, authentication is done via web view. Follow the next steps to make it work:
android-profile uses the Twitter4J library (v 4.0.2) to support Twitter integration
From the downloaded zip, Add the following jars to your project.
AndroidProfileTwitter.jar
twitter4j-core-4.0.2.jar
twitter4j-asyc-4.0.2.jar
Create your Twitter app at https://apps.twitter.com/
Make the following changes in AndroidManifest.xml
:
...
<application ...
<activity android:name="com.soomla.profile.social.twitter.SoomlaTwitter$SoomlaTwitterActivity" android:theme="@android:style/Theme.Translucent.NoTitleBar.Fullscreen">
</activity>
</application>
From the downloaded zip, Add the AndroidProfileGoogle.jar
jar to your project.
Follow Step 1: Enable the Google+ API and create a google+ app for Android.
Note: Set the PACKAGE NAME of your google+ app to the value the package defined in your
AndroidManifest.xml
.
Import google-play-services_lib
project as module dependency to your project.
Note: You can either download/copy the existing
google-play-services_lib
project located under google social provider libs folder or create one yourself.
Add SoomlaGooglePlusActivity
to AndroidManifest.xml
as following:
...
<application ...
<activity android:name="com.soomla.profile.social.google.SoomlaGooglePlus$SoomlaGooglePlusActivity" android:theme="@android:style/Theme.Translucent.NoTitleBar.Fullscreen">
</activity>
</application>
Add the following permissions in AndroidManifest.xml
:
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.GET_ACCOUNTS" />
<uses-permission android:name="android.permission.USE_CREDENTIALS" />
As part of a login call to a provider, Soomla will internally try to also fetch the online user profile details via
UserProfile
and store them in the secure Soomla Storage
Later, this can be retrieved locally (in offline mode) via:
UserProfile userProfile = SoomlaProfile.getInstance().getStoredUserProfile(IProvider.Provider.FACEBOOK) //depending on your provider
This can throw a UserProfileNotFoundException
if something strange happens to the local storage, in that case, you need to require a new login to get the UserProfile
again.
One of the big benefits of using Soomla's profile module for social networks interactions is that you can easily tie it in with the game's virtual economy.
This is done by the ability to specify a Reward
(perhaps more specifically, a VirtualItemReward
) to most social actions defined in SoomlaProfile
.
For example, to reward a user with a "sword" virtual item upon login to Facebook:
Reward reward = new VirtualItemReward([id], "Update Status for sword", 1, "sword");
SoomlaProfile.getInstance().login([activity], IProvider.Provider.FACEBOOK, reward);
Once login completes sucessfully (wait for LoginFinishedEvent
, see below on events), the reward will be automatically given, and synchronized with Soomla's storage.
The reward ID is something you manage and should be unique, much like virtual items.
In order to debug android-profile, set SoomlaConfig.logDebug
to true
. This will print all of android-profile's debugging messages to logcat.
The on-device storage is encrypted and kept in a SQLite database. SOOMLA is preparing a cloud-based storage service that will allow this SQLite to be synced to a cloud-based repository that you'll define.
If you want to protect your game from 'bad people' (and who doesn't?!), you might want to follow some guidelines:
Soomla
and before you release your game. BE CAREFUL: You can change this value once! If you try to change it again, old data from the database will become unavailable.For event handling, we use Square's great open-source project otto. In ordered to be notified of profile related events, you can register for specific events and create your game-specific behavior to handle them.
Your behavior is an addition to the default behavior implemented by SOOMLA. You don't replace SOOMLA's behavior.
In order to register for events:
In the class that should receive the event create a function with the annotation '@Subscribe'. Example:
@Subscribe
public void onLoginFinishedEvent(LoginFinishedEvent loginFinishedEvent) {
...
}
You'll also have to register your class in the event bus (and unregister when needed):
BusProvider.getInstance().register(this);
BusProvider.getInstance().unregister(this);
If your class is an Activity, register in 'onResume' and unregister in 'onPause'.
You can find a full event handler example here.
Full documentation and explanation of otto
The android-profile project contains an example project which shows most of the functionality Profile provides, and the correct setup. In order to run the project follow this steps:
SoomlaAndroidExample
folder in Android Studio (IntelliJ), it contains an IntelliJ projectFacebook Application - You must create a Facebook application and use its details in your Profile-based application (with Facebook)
Facebook ID - The Facebook application's ID must be used in your application, this information should be added to the application's strings.xml
file, under fb_app_id
(App ID). In the AndroidManifest.xml
file add the following:
<application ...
<activity android:name="com.facebook.LoginActivity" />
<meta-data android:name="com.facebook.sdk.ApplicationId" android:value="@string/fb_app_id" />
</application>
Facebook Permissions - Profile will request publish_actions
from the user of the application, to test the application please make sure you test with either Admin, Developer or Tester roles
Callback URL
in your Twitter application settings?AndroidManifest.xml
?SOOMLA appreciates code contributions! You are more than welcome to extend the capabilities of SOOMLA.
Fork -> Clone -> Implement -> Add documentation -> Test -> Pull-Request.
IMPORTANT: If you would like to contribute, please follow our Documentation Guidelines. Clear, consistent comments will make our code easy to understand.
Apache License. Copyright (c) 2012-2014 SOOMLA. http://www.soom.la