-
Notifications
You must be signed in to change notification settings - Fork 10
/
README.rtf
363 lines (268 loc) · 17.4 KB
/
README.rtf
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
{\rtf1\ansi\ansicpg1252\cocoartf1038\cocoasubrtf320
{\fonttbl\f0\fswiss\fcharset0 Helvetica;\f1\fnil\fcharset0 Monaco;\f2\fnil\fcharset0 Menlo-Regular;
}
{\colortbl;\red255\green255\blue255;\red0\green0\blue0;\red0\green0\blue128;}
\margl1440\margr1440\vieww16000\viewh15040\viewkind0
\pard\tx360\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural
\f0\b\fs36 \cf0 \ul \ulc0 Engage for iPhone 2 beta Documentation\
\pard\tx360\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural
\b0\fs24 \cf0 \ulnone \
\b\fs28 Before You Begin\
\b0\fs24 \'95 You need to have created a Janrain Engage application, which you can do on http://rpxnow.com\
\'95 If you would like to do server-side authentication, you'll need to create a token_url\
\
\b\fs28 Overview\
\b0\fs24 \'95 User Experience\
\'95 Components\
\'95 Basic Flow: Authentication\
\'95 Basic Flow: Social Publishing\
\'95 Detailed Flow\
\
\b\fs28 Getting the Library\
\b0\fs24 \'95 Prerequisites\
\'95 Get the Library\
\'95 Add the Library to Xcode\
\
\b\fs28 Using the Library\
\b0\fs24 \'95 Quick Start Guide\
\'95 Server-side Authentication\
\
\b\fs28 More Documentation
\b0\fs24 \
\pard\tx360\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural
\cf0 \'95 iPhone Documentation\
\'95 JREngage API\
\'95 Janrain Engage Documentation\
\'95 Janrain Engage API\
\pard\tx360\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural
\cf0 \
\
\pard\tx360\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural
\b\fs36 \cf0 \ul \ulc0 Overview
\b0\fs24 \ulnone \
\
\pard\tx360\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural
\b\fs28 \cf0 \ul \ulc0 User Experience\
\fs26 \ulnone Authentication:
\fs28 \
\b0\fs24 For an example application demonstrating authentication with the JREngage library, Janrain Quick Sign-In* is available (for free) on the iTunes store: \cf2 itms://itunes.apple.com/us/app/quick-sign-in/id375197510?mt=8\cf0 \
\
\b\fs26 Social publishing:\
\b0\fs24 For an example application demonstrating how you can publish an activity with the JREngage library, Janrain Quick Publish* is available on the iTunes store: itms://itunes.apple.com/us/app/quick-publish/id389229631?mt=8\
\
\fs20 *The Quick Sign-In and Quick Publish applications are free and the source code for both applications ship with the library.
\fs24 \
\
\b\fs28 \ul Components\
\b0\fs24 \ulnone \'95 iPhone Application*\
\'95 JREngage Library\
\'95 Engage/Providers' Servers\
\'95 Web Application* with Token URL (optional)\
\fs20 *Samples come with library\
\fs24 \
\b\fs28 \ul Basic Flow\
\fs26 \ulnone Authentication:\
\b0\fs24 1. User launches the library's dialog and chooses a provider.\
2. The library takes the user to the provider in an embedded webview and they authenticate.\
3. Janrain Engage completes authentication and sends the authentication token and the user's basic authentication information back to the library*.\
4. The library closes the dialog and passes the profile data to the calling application.\
5. The application parses the profile data and the user is signed in.\
6. Optionally, the library can post the token to the token URL, to complete any server-authentication**.\
7. The token URL calls auth_info with the token and application key and can make any additional calls on the Engage API.\
8. If the token URL sends any data back to the library, the library passes the response straight through to the application, and server-side authentication is complete.\
\fs20 * This step has changed from the previous versions of the JREngage library. You can now receive the basic profile data without implementing a token URL on your server.\
** This step has been made optional in this version of the JREngage library.\
\b\fs24 \
\fs26 Social Publishing:\
\b0\fs24 1. The application creates an activity object and populates the object's fields.\
2. The user or the application initiates social publishing, passing the activity object to the library.\
3. The user chooses the providers on which they wish to share and adds their own comments.\
4. If the user is already authenticated, they can post the activity to the provider.\
5. If the user is not authenticated, the library takes them through the authentication process, described above, and then the activity is shared.\
6. The library takes the user to the provider in an embedded webview and they authenticate.\
7. The user can share to multiple providers, and the dialog is closed when the user clicks the "Close" button.\
\
\b\fs28 \ul Detailed Flow (Authentication)\
\fs24 \ulnone Step 1: User signs in from your iPhone application\
\pard\tx360\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural
\b0\fs22 \cf0 The library pops up a modal dialog, and the user chooses their identity provider from the library's list of providers. The library passes this on to the Engage server for processing.\
\pard\tx360\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural
\b\fs24 \cf0 Step 2: Engage handles authentication transaction\
\pard\tx360\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural
\b0\fs22 \cf0 Janrain Engage starts the authentication on behalf of your application and sends the user to the identity provider's webpage in an embedded web view. The provider authenticates the user and asks for approval to sign-in to your application.\
\pard\tx360\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural
\b\fs24 \cf0 Step 3: Engage sends the user's profile to the library\
\pard\tx360\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural
\b0\fs22 \cf0 Upon successful authentication, Engage sends the library the user's basic profile data and the dialog closes.\
\pard\tx360\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural
\b\fs24 \cf0 Step 4: Optionally, the library POSTS the token to the token URL\
\pard\tx360\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural
\b0\fs22 \cf0 If you wish to do any server-side authentication, you can pass the library your server's token URL. The library will continue processing authentication behind-the-scenes by issuing a POST, with the token as a parameter, to the token_url you specified.\
\pard\tx360\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural
\b\fs24 \cf0 Step 5: Use the token to access the authentication data\
\pard\tx360\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural
\b0\fs22 \cf0 Your token_url code calls the Engage API with the token from Step 4 and gets back an Engage response with the OpenID authentication information and profile data, including any extended data.\
\pard\tx360\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural
\b\fs24 \cf0 Step 6: Authenticate the user on your website\
\pard\tx360\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural
\b0\fs22 \cf0 Log the user into your website and create/update user profile with the data received in Step 5. The details of how this is done depends on your website implementation.\
\pard\tx360\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural
\b\fs24 \cf0 Step 7: Send a response back to the library\
\pard\tx360\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural
\b0\fs22 \cf0 After you receive the data in Step 6 and process it on your server, you can send any relevant information back to the library in your response. The library will pass the response to your application. The details of the response depend on your application's implementation.\
\pard\tx360\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural
\fs24 \cf0 \
\
\pard\tx360\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural
\b\fs36 \cf0 \ul \ulc0 Getting the library\
\pard\tx360\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural
\fs26 \cf0 \ulnone \
\fs28 \ul Prerequisites\
\b0\fs24 \ulnone \'95 The iPhone SDK\
\'95 A Janrain Engage application\
\'95 (Optional) A web application (See Google App Engine to quickly build one)\
\'95 The Janrain iPhone library\
\
\b\fs28 \ul Get the Library
\fs26 \ulnone \
\b0\fs24 Download the library:\
http://github.com/janrain/engage.iphone/downloads\
\
Or clone from GitHub:\
\f1\fs22 git clone git://github.com/janrain/engage.iphone.git\
\f0\fs24 \
\b\fs28 \ul Add the Library to Your Xcode Project\
\b0\fs24 \ulnone 1. Open your project in Xcode.\
2. Open the JREngage library in Xcode.\
3. Under the "Groups & Files" pane of the JREngage Xcode project, click the JREngage folder and drag it into the "Groups & Files" pane under your application's Xcode project. \
4. In the dialog,
\b do not
\b0 check the "Copy items" box, make sure the "Recursively create groups..." option is selected, and then click "Add". \
\fs28
\fs24 \
\
\pard\tx360\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural
\b\fs36 \cf0 \ul \ulc0 Using the JREngage Library
\fs28 \
\pard\tx360\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural
\b0\fs24 \cf0 \ulnone \
\b\fs26 You can use the JREngage library in three easy steps:\
\b0\fs24 1. Instantiate the library with your Engage application's Application ID, your server's token URL (optional), and the delegate class that implements the JREngageDelegate protocol\
2. Begin authentication or sharing by calling one of the two "show...Dialog" methods \
3. Implement the JREngageDelegate protocol to receive notifications and profile information for your authenticating users \
\
\b\fs28 \ul Quick Start Guide
\fs26 \
\b0\fs24 \ulnone To begin, sign in to Engage to configure the providers you wish to use for authentication and/or social publishing. You will also need your 20-character Application ID from the Application Info box. \
\
\b\fs26 Initialize\
\b0\fs24 To initialize an instance of the library, pass your Application ID to the JREngage class method
\f2\fs20 \cf3 jrEngageWithAppId:andTokenUrl:delegate:
\f0\fs24 \cf0 which returns a pointer to the shared instance of the JREngage object:\
\pard\tx360\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural
\f2\fs20 \cf3 NSString *appId = @"<your app id>";\
... \
JREngage *jrEngage = [JREngage jrEngageWithAppId:appId andTokenUrl:nil delegate:self];\
\pard\tx360\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural
\f0\fs24 \cf0 \
If you wish to implement server-side authentication you can optionally pass your token URL to this method. Make sure that your delegate class implements the
\f2\fs20 \cf3 JREngageDelegate
\f0\fs24 \cf0 protocol. \
\
\b\fs26 Authenticate\
\b0\fs24 In the section of code where you wish to launch the library's authentication process, send the
\f2\fs20 \cf3 showAuthenticationDialog
\f0\fs24 \cf0 message to your JREngage object: \
\f2\fs20 \cf3 [jrEngage showAuthenticationDialog];\
\f0\fs24 \cf0 \
To receive the user's basic profile data, implement the
\f2\fs20 \cf3 jrAuthenticationDidSucceedForUser:forProvider:
\f0\fs24 \cf0 method from the
\f2\fs20 \cf3 JREngageDelegate
\f0\fs24 \cf0 protocol: \
\pard\tx360\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural
\f2\fs20 \cf3 - (void)jrAuthenticationDidSucceedForUser:(NSDictionary *)profile forProvider:(NSString *)provider \
\{ \
NSString *preferredUserName = [[profile objectForKey:@"profile"] objectForKey:@"preferredUsername"]; \
\pard\tx360\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural
\cf3 UIAlertView *alert = [[[UIAlertView alloc] initWithTitle:[NSString stringWithFormat:\
@"Hello, %@!", preferredUserName] \
message:[NSString stringWithFormat:\
@"You have successfully signed in to %@!", provider]\
delegate:self\
cancelButtonTitle:@"OK"\
otherButtonTitles:nil] autorelease]; \
[alert show]; \
\pard\tx360\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural
\cf3 \}\
\pard\tx360\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural
\f0\fs24 \cf0 \
\b\fs26 Share\
\b0\fs24 If you want to share an activity, first create an instance of the
\f2\fs20 \cf3 JRActivityObject
\f0\fs24 \cf0 and populate the activity object's fields: \
\pard\tx360\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural
\f2\fs20 \cf3 JRActivityObject *activity = [[[JRActivityObject alloc]\
initWithAction:@"added JREngage to her iPhone application!" \
andUrl:@"http://janrain.com"] autorelease];\
\pard\tx360\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural
\f0\fs24 \cf0 \
Then pass the activity to the
\f2\fs20 \cf3 showSocialPublishingDialogWithActivity:
\f0\fs24 \cf0 message: \
\pard\tx360\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural
\f2\fs20 \cf3 [jrEngage showSocialPublishingDialogWithActivity:activity];\
\pard\tx360\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural
\f0\fs24 \cf0 \
\b\fs26 Server-side Authentication\
\b0\fs24 If you would like to access any of the extra features available in Janrain Engage's API or if you would like to complete server-side authentication, you can do so by implementing a token URL that does the following: \
1. Implement a method to which the JREngage library can POST the token \
2. Extract the token \
3. Make a call to auth_info with the token and your application's 40-character Application Key \
4. Parse the profile data returned from the call to auth_info, and do anything to log your user in to your web application, create session cookies, etc. \
5. Use the token to access other Janrain Engage features via the API, such as get_contacts* and map* \
6. Send a response back to the JREngage library with any additional information that your application may need \
\fs20 *Some features may be limited to Pro and Plus customers only.\
\fs24 \
To use your token URL, you can pass it into the
\f2\fs20 \cf3 jrEngageWithAppId:andTokenUrl:delegate:
\f0\fs24 \cf0 method when initializing the shared instance of the library:\
\pard\tx360\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural
\f2\fs20 \cf3 static NSString *appId = @"<your app id>"; static NSString *tokenUrl = @"<your token url>"; \
...\
jrEngage = [JREngage jrEngageWithAppId:appId andTokenUrl:tokenUrl delegate:self];\
\pard\tx360\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural
\f0\fs24 \cf0 \
Alternatively, you can change the token URL at any time using the
\f2\fs20 \cf3 updateTokenUrl: method:
\f0\fs24 \cf0 \
\pard\tx360\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural
\f2\fs20 \cf3 - (void)updateTokenUrl:(NSString*)newTokenUrl;\
\pard\tx360\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural
\f0\fs24 \cf0 \
The JREngage library will only post the token if this value is not null. \
\
Whether or not the library posts the token to the token URL, your iPhone application should not contain the Application Key. \
\
\
\pard\tx360\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural
\b\fs36 \cf0 \ul \ulc0 More Documentation\
\pard\tx360\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural
\fs28 \cf0 \ulnone \
\pard\tx360\tx1440\tx2160\tx2880\tx3600\tx4320\tx5040\tx5760\tx6480\tx7200\tx7920\tx8640\ql\qnatural\pardirnatural
\cf0 iPhone Documentation\
\b0\fs24 For more detailed documentation on using the second version of our JREngage iPhone library, you can use these online docs:\
https://rpxnow.com/docs/iphone_v2\
\b\fs28 \
JREngage API\
\b0\fs24 For the complete API of the JREngage library, please see our API Documentation: \
https://rpxnow.com/docs/iphone_api/index.html\
\b\fs28 \
Janrain Engage Documentation\
\b0\fs24 For a more thorough explanation of Janrain Engage, please see our Engage Documentation:\
https://rpxnow.com/docs\
\b\fs28 \
Janrain Engage API\
\b0\fs24 For documentation on Janrain Engage's APIs, please see our API Documentation:\
https://rpxnow.com/docs#api\
}