Library for easily integrating Tumblr data into your iOS or OS X application.

Tumblr SDK for iOS

An unopinionated and flexible library for easily integrating Tumblr data into your iOS or OS X application. The library uses ARC requires at least iOS 9 or OS X 10.10.

If you have any feature requests, please let us know by creating an issue or submitting a pull request. Please use the Tumblr API responsibly and adhere to the Application Developer and API License Agreement.

Table of Contents

• Getting started
  • CocoaPods
  • Documentation
• Connecting to Tumblr
  • API client
  • Authentication
    • OAuth
  • Attribution and Deep Links
  • Share extension
  • Deprecated Connection Methods
• Example App
• Contact
• License

Getting started

CocoaPods

CocoaPods is the recommended way to add the Tumblr SDK to your project. Using CocoaPods means you don't need to worry about cloning or adding this repository as a git submodule. CocoaPods is a package manager like gem (Ruby) and npm (Node.js), but for Swift and Objective-C projects.

Module authors create "pods" which are versioned and stored in a central repository. App developers create "podfiles" to specify their apps' dependencies and use the CocoaPods command line tool to:

• Fetch the dependencies specified in their podfile
• Recursively fetch all subdependencies
• Create an Xcode workspace that includes the pods, links any necessary libraries, configures header search paths, enables ARC where appropriate, and more

If you're new to CocoaPods, the website contains lots of helpful documentation.

To install the Tumblr SDK you can simply create a podfile in your application's root directory that looks as follows:

platform :ios, '9.0'

pod 'TMTumblrSDK'

After running pod install, you'll have an Xcode workspace that includes not only your application but also the Tumblr SDK. That's really all there is to it.

You will get the latest version of the SDK by referring to it simply by name (TMTumblrSDK). This guide explains how explicit dependency versions can instead be specified.

If you choose to include TMTumblrSDK manually (i.e. without CocoaPods) please make sure that your app can still read TMTumblrSDK.podspec.json. We use this for tracking which versions of TMTumblrSDK are in use, which helps us make informed decisions about the project’s future.

Documentation

Appledoc for the SDK can be found here. If you install the Tumblr SDK using CocoaPods, the docset is automatically added to Xcode for you.

Connecting to Tumblr

API client

Use the TMAPIClient class for communication with Tumblr via the Tumblr API. A typical use case for the API client is an application that allows a user to share a photo to multiple social networks at the same time. In this case, after allowing a user to select a photo, you might present them with a list of toggles representing the different networks that would receive the photo. Once they confirm, and assuming they selected Tumblr, you would use the API client to post the image to the user's Tumblr. Use of the API Client requires authentication from the user for certain routes which you may facilitate through the TMOAuthAuthenticator class.

Please view the API documentation for full usage instructions.

OAuth Authentication

In your AppDelegate, import <TMTumblrSDK/TMOAuthAuthenticator.h>, <TMTumblrSDK/TMURLSession.h>, and TMOAuthAuthenticatorDelegate.h.

Declare constants for your app’s Tumblr consumer key and secret:

NSString * const OAuthTokenConsumerKey = @"";
NSString * const ConsumerSecret = @"";

If you don't already have a consumer key/secret you can register here.

Setup

In your app’s Info.plist, specify a custom URL scheme that the browser can use to return to your application once the user has permitted or denied access to Tumblr:

        <key>CFBundleURLTypes</key>
        <array>
                <dict>
                        <key>CFBundleTypeRole</key>
                        <string>Editor</string>
                        <key>CFBundleURLName</key>
                        <string>com.tumblr.example</string>
                        <key>CFBundleURLSchemes</key>
                        <array>
                                <string>my-sample-app</string>
                        </array>
                </dict>
        </array>

In your app delegate setup your TMURLSession and TMOAuthAuthenticator instances, for example:

- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions {

    self.applicationCredentials = [[TMAPIApplicationCredentials alloc] initWithConsumerKey:OAuthTokenConsumerKey consumerSecret:ConsumerSecret];

    self.session = [[TMURLSession alloc] initWithConfiguration:[NSURLSessionConfiguration defaultSessionConfiguration]
                                        applicationCredentials:self.applicationCredentials
                                               userCredentials:[TMAPIUserCredentials new]
                                        networkActivityManager:nil
                                     sessionTaskUpdateDelegate:nil
                                        sessionMetricsDelegate:nil
                                            requestTransformer:nil
                                             additionalHeaders:nil];

    self.authenticator = [[TMOAuthAuthenticator alloc] initWithSession:self.session
                                                applicationCredentials:self.applicationCredentials
                                                              delegate:self];

    ViewController *vc = [[ViewController alloc] initWithSession:self.session authenticator:self.authenticator];

    self.window = [[UIWindow alloc] initWithFrame:[UIScreen mainScreen].bounds];
    self.window.rootViewController = vc;
    [self.window makeKeyAndVisible];

    return YES;
}

Also add the ability to handle incoming URL requests and also conform to TMOAuthAuthenticatorDelegate

On iOS this looks like:

- (BOOL)application:(UIApplication *)app openURL:(NSURL *)url options:(NSDictionary<UIApplicationOpenURLOptionsKey,id> *)options {
    [self.authenticator handleOpenURL:url];
    return YES;
}

#pragma mark - TMOAuthAuthenticatorDelegate

- (void)openURLInBrowser:(NSURL *)url {
    [[UIApplication sharedApplication] openURL:url];
}

Then, use these instances in an authenticate method in another class such as a view controller, for example

- (void)authenticate {
    [self.authenticator authenticate:@"ello" callback:^(TMAPIUserCredentials *creds, NSError *error) {
        dispatch_async(dispatch_get_main_queue(), ^{
            if (error) {
                self.authResultsTextView.text = [NSString stringWithFormat:@"Error: %@", error.localizedDescription];
            }
            else {
                self.session = [[TMURLSession alloc] initWithConfiguration:[NSURLSessionConfiguration defaultSessionConfiguration] applicationCredentials:[[TMAPIApplicationCredentials alloc] initWithConsumerKey:@"" consumerSecret:@""] userCredentials:[[TMAPIUserCredentials alloc] initWithToken:creds.token tokenSecret:creds.tokenSecret]];
                self.authResultsTextView.text = [NSString stringWithFormat:@"Success!\nToken: %@\nSecret: %@", creds.token, creds.tokenSecret];
                [self request];
            }
        });
    }];
}

Attribution and Deep Links

If your app posts to Tumblr, you can provide the API Client with deep link URLs under the keys TMPostKeyDeepLinkiOS and TMPostKeyDeepLinkAndroid. This will cause attribution UI for your app to be displayed beneath the post on the respective platform. When this UI is tapped, the OS will open the deep link you specified. Be aware that all icons and required fields must be provided in your app's configuration before this UI will be visible.

NOTE: This is currently only available to whitelisted app partners. Contact Tumblr business development (bd@tumblr.com) if your app requires this functionality.

Share extension

As of iOS 8, Tumblr for iOS ships with a share extension. It currently supports the following input types:

• Text
• Images (maximum: 10)
• Video (maximum: 1)
• URL (maximum: 1)

In the future, we hope to document specific ways for apps to pass parameters to be used for creating the different Tumblr post types, but we’d need to figure out a good way to do so that won’t interfere with other share extensions that could also potentially be displayed.

If you're looking to hardcode some Tumblr-specific behavior, our share extension’s bundle identifier is com.tumblr.tumblr.Share-With-Tumblr.

Deprecated Connection Methods

• URL schemes [Deprecated]
• UIActivityViewController [Deprecated]

Example

The repository includes iOS and macOS sample applications.

Contact

• Tumblr iOS
• Tumblr API discussion group

License

Copyright 2012-2017 Tumblr, Inc.

Licensed under the Apache License, Version 2.0 (the “License”); you may not use this file except in compliance with the License. You may obtain a copy of the License at apache.org/licenses/LICENSE-2.0.

Unless required by applicable law or agreed to in writing, software distributed under the License is distributed on an “AS IS” BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. See the License for the specific language governing permissions and limitations under the License.