Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with
or
.
Download ZIP
Newer
Older
100644 225 lines (157 sloc) 8.903 kB
f4e26d2 @zachgraves new readme
zachgraves authored
1 Yahoo! Social SDK, Objective-C library
2 =================
3
68fcc38 @zachgraves fixed all links in readme to actually link to page
zachgraves authored
4 Find documentation and support on Yahoo! Developer Network: [http://developer.yahoo.com](http://developer.yahoo.com/yap/)
f4e26d2 @zachgraves new readme
zachgraves authored
5
68fcc38 @zachgraves fixed all links in readme to actually link to page
zachgraves authored
6 * Yahoo! Application Platform - [http://developer.yahoo.com/yap/](http://developer.yahoo.com/yap/)
7 * Yahoo! Social APIs - [http://developer.yahoo.com/social/](http://developer.yahoo.com/social/)
8 * Yahoo! Query Language - [http://developer.yahoo.com/yql/](http://github.com/yahoo/yos-social-objc/tree/master)
f4e26d2 @zachgraves new readme
zachgraves authored
9
68fcc38 @zachgraves fixed all links in readme to actually link to page
zachgraves authored
10 Hosted on GitHub: [http://github.com/yahoo/yos-social-objc/tree/master](http://github.com/yahoo/yos-social-objc/tree/master)
f4e26d2 @zachgraves new readme
zachgraves authored
11
12 License
13 =======
14
15 Software License Agreement (BSD License)
c6b1478 @zachgraves readme formatting
zachgraves authored
16
f4e26d2 @zachgraves new readme
zachgraves authored
17 Copyright (c) 2009, Yahoo! Inc.
c6b1478 @zachgraves readme formatting
zachgraves authored
18
f4e26d2 @zachgraves new readme
zachgraves authored
19 All rights reserved.
20
c6b1478 @zachgraves readme formatting
zachgraves authored
21 * YOAuth
22 * YOSSocial
f4e26d2 @zachgraves new readme
zachgraves authored
23
24 Redistribution and use of this software in source and binary forms, with
25 or without modification, are permitted provided that the following
26 conditions are met:
27
28 * Redistributions of source code must retain the above
29 copyright notice, this list of conditions and the
30 following disclaimer.
31
32 * Redistributions in binary form must reproduce the above
33 copyright notice, this list of conditions and the
34 following disclaimer in the documentation and/or other
35 materials provided with the distribution.
36
37 * Neither the name of Yahoo! Inc. nor the names of its
38 contributors may be used to endorse or promote products
39 derived from this software without specific prior
40 written permission of Yahoo! Inc.
41
42 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
43 AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
44 IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
45 DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE LIABLE
46 FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
47 DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
48 SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
49 CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
50 OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
51 OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
52
53 This software additionally references or incorporates the following sources
54 of intellectual property, the license terms for which are set forth
55 in the sources themselves:
56
57 Requirements
58 ============
59
0a47a70 @zachgraves updated readme
zachgraves authored
60 The following dependencies are bundled with the Yahoo! Social SDK, but are under
f4e26d2 @zachgraves new readme
zachgraves authored
61 terms of a separate license:
62
68fcc38 @zachgraves fixed all links in readme to actually link to page
zachgraves authored
63 * json-framework - [http://code.google.com/p/json-framework/](http://code.google.com/p/json-framework/)
64 * OAuthConsumer Crypto - [http://oauth.googlecode.com/svn/code/obj-c/OAuthConsumer/Crypto/](http://oauth.googlecode.com/svn/code/obj-c/OAuthConsumer/Crypto/)
f4e26d2 @zachgraves new readme
zachgraves authored
65
66
67 Install
68 =======
69
70 Include the YOAuth, YOSSocial and json-framework groups into your Xcode project path.
71 Then, include the YOSSocial.h header into your code.
72
73 #import "YOSSocial.h"
74
cf70640 @zachgraves added info on synchronous yql queries
zachgraves authored
75
35df9c4 @zachgraves new readme bits on creating an app
zachgraves authored
76 Creating A New Application
77 ========
78
79 To use Yahoo! Web Services, we need some information about you and the application you're building.
80 Sign up for a new application ID to get your OAuth consumer key & secret.
81
68fcc38 @zachgraves fixed all links in readme to actually link to page
zachgraves authored
82 * YDN Developer Dashboard - [https://developer.yahoo.com/dashboard/](https://developer.yahoo.com/dashboard/)
83 * New Application Form - [https://developer.yahoo.com/dashboard/createKey.html](https://developer.yahoo.com/dashboard/)
f4e26d2 @zachgraves new readme
zachgraves authored
84
cf70640 @zachgraves added info on synchronous yql queries
zachgraves authored
85
f4e26d2 @zachgraves new readme
zachgraves authored
86 Examples
87 ========
88
89 ## Creating a Session:
90
91 A session hold three important objects: a YDN Application ID, an OAuth
92 consumer and an OAuth access token. These objects provide the
93 credentials needed to initialize requests and sign using OAuth. To create a
94 new session using YOSSession, initialize it by using your consumer
95 key, consumer secret and application ID you just got as parameters.
96
97 // create a session by passing our
98 // consumer key, consumer secret and application id.
99 YOSSession *session = [YOSSession sessionWithConsumerKey:@"Key"
100 andConsumerSecret:@"Secret"
101 andApplicationId:@"AppID"];
102
103 ## Initializing a Session:
104
105 Because a session can persistent you next check for an existing user session.
106 If a user session does not exist yet, they must login in order for the
107 application to gain access to their protected user information. (profile,
108 connections, updates, etc.) Alternatively, if a session exists, the session
109 will automatically fetch a new access token to renew the session.
110
111 // try to resume a user session if one exists
112 BOOL hasSession = [session resumeSession];
113
114 if(hasSession == FALSE) {
bc79b44 @zachgraves fixed incorrect method name in readme (sendUserToAuthorizationWithCal…
zachgraves authored
115 [session sendUserToAuthorizationWithCallbackUrl:nil];
f4e26d2 @zachgraves new readme
zachgraves authored
116 }else{
117 [self sendRequests];
118 }
119
120 ## Fetching Social Data:
6bfafc0 @zachgraves updated readme
zachgraves authored
121
122 Now that we have a ready session, we can now access social information for
123 the logged-in user. The depth of user data you can access will depend on
124 the permissions for which your application asked.
125
126 Each 'GET' method of YOSUserRequest creates an asynchronous request with the
127 delegate you provided. When the request is returned, the delegate method
128 'requestDidFinishLoading' is invoked with a YOSResponseData object containing
129 the NSHTTPURLResponse object, NSData response object, a responseText string
130 and an NSError object (if an error occurred) for which your application should handle.
131
132 To work with the response data object, parse the response text
133 (defaults to encoded JSON data) using the methods from json-framework.
134
135 - (void)sendRequests {
136 // initialize a user request for the logged-in user
137 YOSUserRequest *request = [YOSUserRequest requestWithSession:session];
138
139 // fetch the user's profile data
b5e379b @zachgraves more readme updates
zachgraves authored
140 YOSResponseData *userProfileResponse = [request fetchProfileWithDelegate:self];
288e3f3 @zachgraves fixed indents
zachgraves authored
141 }
6bfafc0 @zachgraves updated readme
zachgraves authored
142
143 - (void)requestDidFinishLoading:(YOSResponseData *)data {
144 // parse the response text string into a dictionary
145 NSDictionary *rspData = [data.responseText JSONValue];
146 NSDictionary *profileData = [rspData objectForKey:@"profile"];
147
148 // format a string using the nickname object from the profile.
149 NSString *welcomeText = [NSString stringWithFormat:@"Hey %@ %@!",
150 [profileData objectForKey:@"givenName"],
151 [profileData objectForKey:@"familyName"]];
288e3f3 @zachgraves fixed indents
zachgraves authored
152 }
6bfafc0 @zachgraves updated readme
zachgraves authored
153
154 ## Posting User Activities
155
156 Yahoo! provides two means for you to share your user's activities back to other Yahoo! users:
157
158 Status: A line of text describing what a user is currently doing.
159
160 Updates: A user's stream of shared activities. (Each containing, at the very least, a
161 line of developer-supplied text, your icon and a link back to your application.)
162
163 You can use these channels to advertise your user's use of your app to a
164 large audience of Yahoo! users, driving this larger group to your product.
165
166 The sample code below shows how to set a user's status and post an update
167 to their activity stream.
168
169 Status:
170
b5e379b @zachgraves more readme updates
zachgraves authored
171 // get the logged-in user
172 YOSUserRequest *request = [YOSUserRequest requestWithSession:session];
6bfafc0 @zachgraves updated readme
zachgraves authored
173
b5e379b @zachgraves more readme updates
zachgraves authored
174 // set the user's current status message
175 [request setStatus:@"is hacking"];
6bfafc0 @zachgraves updated readme
zachgraves authored
176
177 Updates:
178
179 YOSUserRequest *request = [YOSUserRequest requestWithSession:session];
180
181 [request insertUpdateWithTitle:@"installed Foo app on their iPhone"
182 andDescription:@""
183 andLink:@"http://myapplication.com/download"
184 andDate:nil
185 andSuid:[request generateUniqueSuid]];
186
187 ## Using YQL
188
cf70640 @zachgraves added info on synchronous yql queries
zachgraves authored
189 Synchronous :
190
191 YQLQueryRequest *request = [YQLQueryRequest requestWithSession:self.session];
192
193 NSString *structuredLocationQuery = [NSString
194 stringWithFormat:@"select * from geo.places where text=\"sfo\""];
195
196 YOSResponseData *data = [request query:structuredLocationQuery];
197 NSDictionary *rspData = [data.responseText JSONValue];
198 NSDictionary *queryData = [rspData objectForKey:@"query"];
199 NSDictionary *results = [queryData objectForKey:@"results"];
200
201 NSLog(@"%@", [results description]);
202
203 Asynchronous:
204
6bfafc0 @zachgraves updated readme
zachgraves authored
205 - (void)sendRequests {
cf70640 @zachgraves added info on synchronous yql queries
zachgraves authored
206 YQLQueryRequest *request = [YQLQueryRequest requestWithSession:self.session];
6bfafc0 @zachgraves updated readme
zachgraves authored
207
b5e379b @zachgraves more readme updates
zachgraves authored
208 NSString *structuredLocationQuery = [NSString
6bfafc0 @zachgraves updated readme
zachgraves authored
209 stringWithFormat:@"select * from geo.places where text=\"sfo\""];
210
b5e379b @zachgraves more readme updates
zachgraves authored
211 [request query:structuredLocationQuery withDelegate:self];
6bfafc0 @zachgraves updated readme
zachgraves authored
212 }
213
214 - (void)requestDidFinishLoading:(YOSResponseData *)data {
215 NSDictionary *rspData = [data.responseText JSONValue];
216 NSDictionary *queryData = [rspData objectForKey:@"query"];
217 NSDictionary *results = [queryData objectForKey:@"results"];
218
219 NSLog(@"%@", [results description]);
220 }
cf70640 @zachgraves added info on synchronous yql queries
zachgraves authored
221
6bfafc0 @zachgraves updated readme
zachgraves authored
222 ## Terms of Use
223
224 Use of the Yahoo! Social APIs is governed by the [Yahoo! APIs Terms of Use](http://developer.yahoo.com/terms/).
225 Your use of YQL is subject to the [YQL Terms of Service](http://info.yahoo.com/legal/us/yahoo/yql/yql-4307.html).
Something went wrong with that request. Please try again.