A simple SDK for accessing Singly from iOS apps.
The first thing you will need is a Client ID and a Client Secret for your application from Singly. If you have not done so already, add your application by signing in to Singly. Your Client ID and Client Secret can be found on the application settings page for your application.
Once you have your Client ID and Client Secret, we can either start a new iOS application or use an existing one. If you are starting fresh, you can take a look at and clone our skeleton project that is already bootstrapped for the Singly iOS SDK.
The easiest way to get started with the Singly SDK is to download our pre-packaged distribution.
-
Drag the
SinglySDK.frameworkandSinglySDK.bundlefiles from the pre-packaged distribution into your Xcode project. You will be asked to add them to your targets; do this. -
The Singly SDK requires a number of frameworks that you may or may not already be linking to. Under your Build Phases setting, add the
Accounts,AddressBook,AddressBookUI,Security,Social,TwitterandQuartzCoreframeworks to the "Link Binary With Libraries" phase. If you are targeting iOS 5, be sure to mark theSocialframework as "Optional" instead of "Required". -
Import the Singly SDK into the source files you wish to use the SDK in by using
#import <SinglySDK/SinglySDK.h>.
To start using the Singly SDK in your project, you will first need to
initialize the SinglySession. You'll probably want to do this in your
application delegate right after the application has finished launching, such
as in the application:didFinishLaunchingWithOptions:launchOptions method.
SinglySession *session = [SinglySession sharedSession];
session.clientID = CLIENT_ID;
session.clientSecret = CLIENT_SECRET;
[session startSessionWithCompletion:^(BOOL isReady, NSError *error) {
if (isReady) {
// The session is ready to go!
} else {
// A valid session could not be started. You will need to authenticate
// with a service (from a view controller) to establish a valid
// session.
}
}];The SinglySession has two other properties:
accessToken- Your Singly Access Token. You should not need to access this unless you really need to do something that does not fit into the current Singly SDK.accountID- Your Singly Account ID.
Both of these are saved between runs in the NSUserDefaults and should be
setup using SinglyService or a SinglyLoginViewController instance.
The Singly iOS SDK attempts to provide the best possible user experience, based on the service the user wishes to authenticate with and the support that we have for that service on the device they are using. To request authorization, call the following from a view controller to present the login view for a given service:
SinglyService *service = [SinglyService serviceWithIdentifier:@"facebook"];
service.delegate = self;
[service requestAuthorizationFromViewController:self];The delegate for the service you are requesting authorization from should
adhere to the SinglyServiceDelegate protocol. These methods will be called
after the authorization request has completed:
- (void)singlyServiceDidAuthorize:(SinglyService *)service
{
// We're ready to rock! Go do something amazing!
}
- (void)singlyServiceDidFail:(SinglyService *)service
withError:(NSError *)error
{
UIAlertView *alert = [[UIAlertView alloc] initWithTitle:@"Login Error"
message:[error localizedDescription]
delegate:self cancelButtonTitle:@"OK"
otherButtonTitles:nil];
[alert show];
[self dismissViewControllerAnimated:YES completion:nil];
}If you wish to login multiple services, or offer multiple services for login,
then you can use the SinglyLoginPickerViewController.
SinglyLoginPickerViewController *viewController = [[SinglyLoginPickerViewController alloc] init];
[self presentModalViewController:viewController animated:YES];
Once we have a valid session we can start making API requests. We can make
GET, POST or any method requests using the SinglyRequest class (which is
simply a convenient subclass of NSURLRequest). The request is only a
description of the request that we are going to make, to actually execute
the request we use NSURLConnection.
Here is an example that requests the profiles list and uses blocks to handle the result:
SinglyRequest *request = [SinglyRequest requestWithEndpoint:@"profiles"];
[NSURLConnection sendAsynchronousRequest:request
queue:[NSOperationQueue mainQueue]
completionHandler:^(NSURLResponse *response, NSData *data, NSError *error) {
NSArray *profiles = [NSJSONSerialization JSONObjectWithData:data options:kNilOptions error:nil];
NSLog(@"The profiles result is: %@", profiles);
}];Singly SDK ships with an example app that illustrates all of the capabilities of the SDK.
Before you can build and run the example app, you will need to provide your
Client ID and Client Secret in SinglyConfiguration.h.
See the instructions below (under "Native Facebook Authorization") to enable testing of the Facebook application fallback attempt.
Once you have things configured, simply build and run the project in the Simulator.
If you wish to run the example on your iPhone or iPad, you will need to configure the project with provisioning appropriate to your device and Apple developer account, which is beyond the scope of this document.
After you've cloned the project, you will find generated documentation in
the SinglySDK/Documentation folder. This documentation is automatically
regenerated with each successful build of the framework in Xcode, provided
you have appledoc installed.
You may also view the documentation for the latest release at http://singly.github.com/iOS-SDK/api or subscribe to it within Xcode at http://singly.github.com/iOS-SDK/api/SinglySDK.atom.
Singly SDK interfaces directly with the device to support authorization on iOS 6+ and will attempt to fallback to the installed Facebook application and then the built-in Singly web-based authorization. In order for the Facebook application fallback to work, you will need to perform the following steps:
On the Facebook Developers site, you will need to create and configure your app as a "Native iOS App". You will need to set the bundle identifier defined in your Info.plist.
You must add the following to your Info.plist, replacing the 0's with your actual Facebook App ID:
<key>CFBundleURLTypes</key>
<array>
<dict>
<key>CFBundleURLSchemes</key>
<array>
<string>fb000000000000000</string>
</array>
</dict>
</array>When native integration is not possible, we fall back to launching the Facebook app (if installed) in order to complete the auth workflow. In order for this to happen, you will need your application delegate to implement the following method in order for the round-trip process to complete:
- (BOOL)application:(UIApplication *)application
openURL:(NSURL *)url
sourceApplication:(NSString *)sourceApplication
annotation:(id)annotation
{
return [SinglySession.sharedSession handleOpenURL:url];
}We are available to answer your questions, help you work through integration issues and look into possible bugs with our service and SDKs.
-
Found a bug? If you think you have come across a bug in the SDK, please take a moment to file an issue, providing as much information about the issue as possible.
-
File a support ticket. For questions or help implementing the SDK into your app, feel free to contact support.
You may also contact the maintainer of the Singly iOS SDK, Justin Mecham, at [email protected].
The Singly iOS SDK is licensed under the terms of the BSD License. Please see the LICENSE file for more information.