This project is a part of The SOCIAL Framework, which is a series of open source initiatives with a joint goal to help mobile game developers do more together. SOCIAL encourages better game design, economy modeling, social engagement, and faster development.
Haven't you ever wanted an in-app purchase one liner that looks like this ?!
[[SocialProfile getInstance] updateStatusWithProvider:FACEBOOK
andStatus:@"I Love This GAME !"
andReward:appDelegate.updateStatusReward];
ios-profile
SOCIAL's Profile Module for iOS
November 17th: v1.0 ios-profile supports Facebook, Google+ and Twitter
ios-profile is an open code initiative as part of The SOCIAL Project. It is an Objective-C API that unifies interaction with social and identity providers 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.
Download
####Pre baked libraries:
Getting Started
WE USE ARC !
- The static libs and headers you need are in the zip you downloaded from the link above.
- Set your project's "Library Search Paths" and "Header Search Paths" to that folder with
recursive
option. - Add
-ObjC -lSoomlaiOSProfile -lSoomlaiOSCore
to the project's "Other Linker Flags".
-
Make sure you have the following frameworks in your application's project: Security, libsqlite3.0.dylib.
-
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 initializeWithSecret:@"[YOUR CUSTOM GAME SECRET HERE]"];
The secret is your encryption secret for data saved in the DB.
-
If integrating a virtual economy with the store module, please see ios-store for store setup.
-
Initalize Soomla Profile:
[[SocialProfile getInstance] initialize];
Note that some providers will need initialization parameters (see their sections below), in that case you'll need to supply their parameters here, each with its dictionary:
NSDictionary* providerParams = @{ @([provider]) : @{...}
... };
[[SocialProfile getInstance] initialize:providerParams];
-
Facebook - No parameters
-
Google+ - Please provide CLIENT ID from the "API&Auth" -> "Credentials" -> "Client ID for iOS applicatio" section in Google Developer Console Projects, like so:
objective-c @(GOOGLE) : @{ @"clientId": @"[CLIENT ID]" }
-
Twitter - Please provide Consumer Key and Consumer Secret from the "Keys and Access Tokens" section in Twitter Apps, like so:
objective-c @(TWITTER) : @{ @"consumerKey": @"[YOUR CONSUMER KEY]", @"consumerSecret": @"[YOUR CONSUMER SECRET]" }
- (OPTIONAL) You can supply the
forceWeb
key in the parameters (with aBOOL
) value if you would like to force browser-based authorization, like so:
@(TWITTER): @{ ..., @"forceWeb": @(YES) },
- (OPTIONAL) You can supply the
-
Refer to the next section for information of selecting social providers and setting them up.
-
Access the Profile functionality through
SocialProfile
[[SocialProfile getInstance] ...];
And that's it ! You have social network capabilities.
What's next? Selecting Social Providers
ios-profile is structured to support multiple social networks (Facebook, Twitter, etc.), at the time of writing this the framework only supports Facebook, Twitter and Google+ integration.
Facebook is supported out-of-the-box, you just have to follow the next steps to make it work:
-
Add the Facebook SDK for iOS to the project's Frameworks and make sure your project links to the project
-
Refer to Getting Started with the Facebook iOS SDK for more information
-
Add
-lSoomlaiOSProfileFacebook
to the project's "Other Linker Flags"
Twitter is supported out-of-the-box, authentication is done either through the signed in Twitter account (iOS 5+) or through web browser (fallback). Follow the next steps to make it work:
-
Create your Twitter app at https://apps.twitter.com/
-
Add a URL scheme to your application:
-
Go to the application's "Info" section in the build target
-
Under "URL Types" add a new URL type
-
In the "URL Schemes" fill in
tw<Your Twitter app consumer key>
(without the braces) -
Make sure you have the following frameworks in your application's project: Twitter, Social, Accounts.
-
Add
-lSoomlaiOSProfileTwitter -lSTTwitter
to the project's "Other Linker Flags"
ios-profile uses the STTWitter library (v 0.1.5) to support Twitter integration
Google Plus
Google Plus is supported out-of-the-box, authentication is done either through the signed in Google Plus account or through web browser (fallback). Follow the next steps to make it work:
- Follow Step 1. Creating the Google Developers Console project and create a google+ app for iOS.
NOTE: Set the BUNDLE ID of the google+ app to the bundle identifier of your app.
-
Follow Step 3. Add a URL type and add url type to your application to allow browser based authentication.
-
Navigate to social-providers/ios-profile-google/libs and add the following frameworks to your application:
- GooglePlus.framework
- GoogleOpenSource.framework
- GooglePlus.bundle
ios-profile uses Google Plus SDK 1.7.1 to support Google Plus integration.
-
Add additional frameworks to your project:
- AddressBook.framework
- AssetsLibrary.framework
- Foundation.framework
- CoreLocation.framework
- CoreMotion.framework
- CoreGraphics.framework
- CoreText.framework
- MediaPlayer.framework
- Security.framework
- SystemConfiguration.framework
- UIKit.framework
-
Add
-lSoomlaiOSProfileGoogle
to the project's "Other Linker Flags"
Browser-based Authentication
Most social framework SDKs support authentication through your web browser, when the user finishes authenticating through the browser your application will be called dependent on the URL schemes you have defined.
The callback to this process is openURL
which should be defined in your AppDelegate
, ios-profile provides you with a helper method to handle the openURL
callback through its providers. Add the following code to your AppDelegate
to handle this properly:
- (BOOL)application:(UIApplication *)application
openURL:(NSURL *)url
sourceApplication:(NSString *)sourceApplication
annotation:(id)annotation
{
BOOL urlWasHandled = [[SocialProfile getInstance] tryHandleOpenURL:url sourceApplication:sourceApplication annotation:annotation];
if (urlWasHandled) {
return urlWasHandled;
}
// Profile was unable to handle callback, do some custom handling
return NO;
}
UserProfile
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 = [[SocialProfile getInstance] getStoredUserProfileWithProvider:FACEBOOK];
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.
Rewards feature
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 SocialProfile
.
For example, to reward a user with a "sword" virtual item upon login to Facebook:
Reward *reward = [[VirtualItemReward alloc] initWithRewardId:@"..."
andName:@"Update Status for sword"
andAmount:1
andAssociatedItemId:@"sword"];
[[SocialProfile getInstance] loginWithProvider:FACEBOOK andReward:reward];
Once login completes sucessfully (wait for EVENT_UP_LOGIN_FINISHED
), 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.
Debugging
In order to debug ios-profile, set DEBUG_LOG
(see SoomlaConfig) to YES
. This will print all of ios-profile's debugging messages to Log Navigator.
Storage
The on-device storage is encrypted and kept in a SQLite database. SOCIAL is preparing a cloud-based storage service that will allow this SQLite to be synced to a cloud-based repository that you'll define.
Security
If you want to protect your application from 'bad people' (and who doesn't?!), you might want to follow some guidelines:
- SOCIAL keeps the game's data in an encrypted database. In order to encrypt your data, SOCIAL generates a private key out of several parts of information. Soomla's secret (before v3.4.0 is was known as custom secret) is one of them. SOCIAL recommends that you change this value 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.
Event Handling
SOCIAL lets you get notifications on various events and implement your own application specific behavior.
Your behavior is an addition to the default behavior implemented by SOCIAL. You don't replace SOCIAL's behavior.
In order to observe store events you need to import EventHandling.h
and then you can add a notification to NSNotificationCenter
:
[[NSNotificationCenter defaultCenter] addObserver:self selector:@selector(yourCustomSelector:) name:EVENT_UP_LOGIN_STARTED object:nil];
OR, you can observe all events with the same selector by calling:
[UserProfileEventHandling observeAllEventsWithObserver:self withSelector:@selector(yourCustomSelector:)];
Example Project
The ios-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:
- NOTE: The example project is dependent upon ios-store and assumes the project is cloned in a sibling folder to ios-profile. Refer to ios-store on instructions on how to clone the project
- Open the
SoomlaiOSProfileExample.xcodeproj
project in XCode - Run the project on Simulator or on Device
Facebook Caveats
-
Facebook Application - You must create a Facebook application and use its details in your Profile-based application (with Facebook)
-
Facebook ID and Display name - The Facebook application's ID and Name must be used in your application, this information must be added to the application's
plist
file, underFacebookAppID
(App ID) andFacebookDisplayName
(Application name) -
URL Schemes and openURL - To support web-based authorization and dialogs the application needs to handle URL schemes (see here for more information):
-
Under the project's info add an entry to
URL Types
and underURL Schemes
add the stringfbxxxxxxx
the x's should be replaced with your Facebook App ID. -
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
Twitter Caveats
- Login method returns 401 error - this could be the result of a few issues:
- Have you supplied the correct consumer key and secret in
SocialProfile
initialization? - Have you supplied a
Callback URL
in your Twitter application settings?
Google Plus Caveats
- 401. That's an error. Error:invalid_client - this could be the result of a few issues:
- Have you supplied the correct client id in
SocialProfile
initialization? - Does your google+ app BUNDLE ID equal to the Bundle Identifier of your iOS app?
- Did you add a URL type with identifier and Url Schemes set to your Bundle Identifier?
- Did you add all required the frameworks?
Our way of saying "Thanks !"
Other open-source projects that we use:
Contribution
SOCIAL appreciates code contributions! You are more than welcome to extend the capabilities of SOCIAL.
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.
SOCIAL, Elsewhere ...
License
Apache License. Copyright (c) 2012-2014 SOCIAL. http://project.soom.la