Using the Yahoo! Social APIs with Cocoa & Cocoa Touch

Getting Started

Requirements

• Xcode development tools
• OS X 10.5 (Leopard) or higher
• iPhone Sample Code / iPhone OS 2.0+ (optional)

Creating A New Application

In order to start working with the Sample Code, you'll need to get a new client-based application ID and OAuth consumer key and secret. These keys will provide you with general access to the Yahoo! Social Platform, and allow your users to authorize your application to access protected resources and information.

You can get a new application here, or view your current apps in My Projects.

Get The Sample Code

The source code and sample application is hosted publicly on GitHub at http://github.com/yahoo/yos-social-objc.

Adding the Sample Code to your Xcode project

1. Download: From the project page on GitHub, click download and choose a .zip or .tar package. (Or, you can choose to fork the project into your own repository and check out the source code.)
2. Open YahooSocialSdk.xcodeproj into Xcode. Drag the YOAuth, YOSSocial and json-framework groups into your Xcode project's "Groups & Files" sidebar.
3. Include the YOSSocial.h header into your code.
#import "YOSSocial.h"

Note: The Sample Code uses the open-source json-framework project. For the latest and greatest version of json-framework, check out the project page.

Using the Sample Code

Creating a session:

A session hold three important objects: a YDN Application ID, an OAuth consumer and an OAuth access token. These objects provide the credentials needed to initialize requests and sign using OAuth. To create a new session using YOSSession, initialize it by using your consumer key, consumer secret and application ID you just got as parameters.

Because a session can persistent you next check for an existing user session. If a user session does not exist yet, they must login in order for the application to gain access to their protected user information. (profile, connections, updates, etc.) Alternatively, if a session exists, the session will automatically fetch a new access token to renew the session.

Fetching User Data

Now that we have a ready session, we can now access social information for the logged-in user. The depth of user data you can access will depend on the permissions for which your application asked.

Each 'GET' method of YOSUserRequest creates an asynchronous request with the delegate you provided. When the request is returned, the delegate method 'requestDidFinishLoading' is invoked with a YOSResponseData object containing the NSHTTPURLResponse object, NSData response object, a responseText string and an NSError object (if an error occurred) for which your application should handle.

To work with the response data object, parse the response text (defaults to encoded JSON) using the methods from json-framework.

Posting User Activities

Yahoo! provides two means for you to share your user's activities back to other Yahoo! users:

• Status: A line of text describing what a user is currently doing.
• Updates: A user's stream of shared activities. (Each containing, at the very least, a line of developer-supplied text, your icon and a link back to your application.)

You can use these channels to advertise your user's use of your app to a large audience of Yahoo! users, driving this larger group to your product.

The sample code below shows how to set a user's status and post an update to their activity stream.

Using YQL

Using Yahoo! Query Language (YQL) in your applications lets you query for data across many other Yahoo! APIs and other data sources across the internet. Learn more about Yahoo! Query Language (YQL) here.

The sample query below gets the user's location and queries the GeoPlanet API in order to return structured place data.

Good Things To Know

User Authorization & Security

It is important to maintain the trust with the user that OAuth encourages. To that point, when you ask the user to login it is very important that they only enter their credentials within their web-browser and allow the user to visually confirm they are on Yahoo! via the URL bar, HTTPS padlock and anti-phishing tools. Using an embedded WebKit control for example, breaks a fundamental element of OAuth and potentially exposes the user to phishing attempts, because there is no way to confirm the location of the browser. While embedded browsers can be utilized in some applications, Yahoo! requires the presentation of the OAuth authorization process to occur in the device's default web browser.

Assets

Check out the pre-designed sign-in buttons on the Yahoo! Updates Assets page.

Support

Questions and suggestions on the Sample Code are discussed on the YOS Developer forum. If you have any questions or need technical support, please use this forum.

Terms of Use

Use of the Yahoo! Social APIs is governed by the Yahoo! APIs Terms of Use.

Your use of YQL is subject to the YQL Terms of Service.

Resources

• YOS Documentation Home
• OAuth Introduction
• Fire Eagle - Best Practices for OAuth
• Apple - Cocoa & Cocoa Touch Frameworks
• Apple - Developer Tools