Thanks for checking out the Pocket SDK. With a few lines of code, your app can quickly add support for saving URLs to users’ Pocket lists.
The Pocket SDK is the fastest way to add Pocket integration to any iOS or Mac application. Adding the Pocket SDK to your app is incredibly easy. Follow the steps below and you can be saving urls to Pocket from your app within 15 minutes.
You can download the SDK at: http://getpocket.com/api/v3/pocket-objc-sdk.zip
You can also watch/checkout the SDK from GitHub at: http://github.com/pocketco/Pocket-ObjC-SDK. If you use recommend adding the Pocket SDK as a git submodule of your project by running git submodule add git://github.com/Pocket/Pocket-ObjC-SDK.git <path> from the root directory of your repository, replacing the <path> with the path you'd like it installed to.
If you use CocoaPods, you can add the PocketAPI pod to your Podfile. Then run pod install, and the Pocket SDK will be available in your project. See the documentation on the CocoaPods website if you want to set up a new or existing project.
The project download includes the SDK and an example project.
The SDK includes all necessary source files and does not have any other dependencies.
When you register your app with Pocket, it will provide you with a platform consumer key. This key identifies your app to Pocket’s API.
If you have not obtained a consumer key yet, you can register one at http://getpocket.com/api/signup
Once you have the consumer key for the platform you are supporting, the application must register a URL scheme to receive login callbacks. By default, this is “pocketapp” plus your application’s ID (which you can find at the beginning of the consumer key before the hyphen). So if your consumer key is 42-abcdef, your app ID is 42, and your URL scheme will be “pocketapp42”.
If there are already URL schemes in your app’s Info.plist, you can either add the new URL scheme, or use an existing scheme by calling [[PocketAPI sharedAPI] setURLScheme:@"YOUR-URL-SCHEME-HERE"]. To add a URL Scheme, create a block like the one below in your Info.plist, updating it with the app’s scheme:
▾ URL Types (Array)
▾ Item 0 (Dictionary)
URL Identifier (String) com.getpocket.sdk
▾ URL Schemes (Array) (1 item)
Item 0 (String) [YOUR URL SCHEME, like "pocketapp42"]
Or you can copy and paste the following into the XML Source for the Info.plist:
<key>CFBundleURLTypes</key>
<array>
<dict>
<key>CFBundleURLName</key>
<string>com.readitlater</string>
<key>CFBundleURLSchemes</key>
<array>
<string>pocketapp9553</string>
</array>
</dict>
</array>
The final steps to set up the Pocket SDK requires adding a few lines of code to your main app delegate. This is the class where you include iOS required methods like applicationDidFinishLaunching.
At the top of your app delegate source file (and anywhere you call the PocketAPI object), you’ll need to include the PocketAPI header. At the top of your class you’ll probably see other imports already. Simply add this line:
#import “PocketAPI.h”
The Pocket SDK requires your consumer key in order to make any requests to the API. Call this method with your registered consumer key when launching your app:
[[PocketAPI sharedAPI] setConsumerKey:@"Your Consumer Key Here"];
The final step is to give the SDK an opportunity to handle incoming URLs. If you do not already implement this method on your app delegate, simply add the following method:
-(BOOL)application:(UIApplication *)application
openURL:(NSURL *)url
sourceApplication:(NSString *)sourceApplication
annotation:(id)annotation{
if([[PocketAPI sharedAPI] handleOpenURL:url]){
return YES;
}else{
// if you handle your own custom url-schemes, do it here
return NO;
}
}
At this point you’ve properly installed the SDK and can now start making requests and saving urls to Pocket. Here is a two line example:
NSURL *url = [NSURL URLWithString:@”http://google.com”];
[[PocketAPI sharedAPI] saveURL:url handler: ^(PocketAPI *API, NSURL *URL, NSError *error){
if(error){
// there was an issue connecting to Pocket
// present some UI to notify if necessary
}else{
// the URL was saved successfully
}
}];
The example above uses blocks which requires iOS 4.0 or greater. If you have a need to support iOS 3.0, you can use the [linkto:delegate or operation based methods].
Following Pocket’s API best practices, you’ll want to provide a way for the user to manage what account they are logged into. This is most commonly handled by adding a setting in your app’s option screen that lets the user configure their Pocket account. When the user taps this, you can simply call one line of code which will handle the entire authorization process:
[[PocketAPI sharedAPI] loginWithHandler: ^(PocketAPI *API, NSError *error){
if (error != nil)
{
// There was an error when authorizing the user. The most common error is that the user denied access to your application.
// The error object will contain a human readable error message that you should display to the user
// Ex: Show an UIAlertView with the message from error.localizedDescription
}
else
{
// The user logged in successfully, your app can now make requests.
// [API username] will return the logged-in user’s username and API.loggedIn will == YES
}
}];
It is also recommended to observe changes to the PocketAPI’s username and loggedIn properties to determine when the logged-in user changes. If iOS terminates your application while it is in the background (e.g. due to memory constraints), any pending login attempts are automatically saved and restored at launch if needed. Therefore, your delegate/block responses may not get called. If you need to update UI when the logged in user changes, register for observers on PocketAPI at application launch.
To call other arbitrary APIs, pass the API’s method name, the HTTP method name, and an NSDictionary of arguments. An NSDictionary with the response from the API will be passed to the handler.
NSString *apiMethod = ...;
PocketAPIHTTPmethod httpMethod = ...; // usually PocketAPIHTTPMethodPOST
NSDictionary *arguments = ...;
[[PocketAPI sharedAPI] callAPIMethod:apiMethod
withHTTPMethod:httpMethod
arguments:arguments
handler: ^(PocketAPI *api, NSString *apiMethod, NSDictionary *response, NSError *error){
// handle the response here
}];
The Pocket SDK uses the following open source software:
Copyright (c) 2012 Read It Later, Inc.
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the “Software”), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED “AS IS”, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.