-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathReadme.html
231 lines (167 loc) · 10.1 KB
/
Readme.html
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
<?xml version="1.0" encoding="UTF-8" standalone="yes" ?>
<!DOCTYPE html>
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta name="keywords" content="MultiMarkdown, Markdown, XML, XHTML, XSLT, PDF"/>
<link type="text/css" rel="stylesheet" href="css/print.css"/>
<link type="text/css" rel="stylesheet" href="css/doc-less.css"/>
</head>
<body>
<p>Feel free to download and mess around with this app, it may or may not be updated regularly, when it is we will publicise on our twitter feed (@BlueVia)</p>
<h2 id="getyourxcodeenvironmentprepared">Get your X Code environment prepared</h2>
<p>The library and the demo applications are written with XCode 4</p>
<p>The library is in the folder “BlueVia4ObjectiveC” and includes 4 external packages:</p>
<ul>
<li><a href="http://code.google.com/p/oauth/">OACounsumer</a>: The core oAuth routines (Obj-c 2.0), slightly changed to support BlueVia (see github history)</li>
<li><a href="http://http://www.tbxml.co.uk/TBXML/TBXML_Free.html">TBXML</a>: A small XML library to work with XML results from the Advertising API</li>
<li><a href="/https://github.com/stig/json-framework">SBJSON</a>: A small JSON library</li>
<li><a href="http://gorgando.com/blog/tag/sfhfkeychainutils">SFHFKeychainUtils</a>: A small library to easily read and write from the iPhone keychain</li>
</ul>
<p>Additionally the sample code contains two projects using the BlueVia library</p>
<ul>
<li>An iPhone application (tested with iOS SDK 4.2, 4.3). You can find it in the folder “BlueVia4iPhone”</li>
<li>An OS X application (tested with OS X SDK 10.6). You can find it in the folder “BlueVia4OSX”</li>
</ul>
<p>Both projects use the files in the library (linked and not copied to the project folders)</p>
<p>The three TabBar icons in the iPhone app are taken from <a href="http://glyphish.com/">GLYPHISH</a></p>
<h2 id="sampleusageofallblueviaobjectivecroutines">Sample usage of all BlueVia Objective C routines</h2>
<h3 id="setupandpersonalsettings">Setup and personal settings</h3>
<p>Rename BlueViaConfig_template.h to BlueViaConfig.h</p>
<p>For the iPhone app it looks like:</p>
<pre><code> static NSString* consumerKey1 = @"xxxxxxxxxxxxxxxx";
static NSString* consumerSecret1 = @"xxxxxxxxxxxx";
static NSString* adSpaceId = @"xxxxx";
static NSString* appName = @"BlueVia4iPhone";
</code></pre>
<p>And for the OS X app it has two more keys for a 2 legged Advertising call:</p>
<pre><code> static NSString* consumerKey1 = @"xxxxxxxxxxxxxxxx";
static NSString* consumerSecret1 = @"xxxxxxxxxxxx";
static NSString* consumerKey2 = @"xxxxxxxxxxxxxxxx";
static NSString* consumerSecret2 = @"xxxxxxxxxxxx";
static NSString* adSpaceId = @"xxxxx";
static NSString* appName = @"BlueVia4OSX";
</code></pre>
<p>Create an application at the <a href="https://www.bluevia.com">BlueVia portal</a> using all available API’s.
The value of the field “key” needs to be added as “consumerKey1” in both apps. And the value of the field “secret” needs to be added as “consumerSecret1” in both apps.
If you want to use 2-legged oAuth for Advertising, you additionally need to create an app in the BlueVia portal that only uses the Advertising API. Add “key” and “secret” in the same way to “consumerKey2” and “consumerSecret2”.
In bosth cases add the ad Space Id that you receive with your app credentials.</p>
<h3 id="initializetheblueviaobject">Initialize the BlueVia object</h3>
<p>First, create the bluevia object</p>
<pre><code> // 3 legged credentials, oAuth DAnce required
bluevia = [[BlueVia alloc] initWithConsumer:consumerKey1
secret:consumerSecret1
adSpaceId:adSpaceId
appName:appName
delegate:self];
</code></pre>
<p>Then try to retrieve the access token from the keychain (if it was written to it after the last successful appauthorisation)</p>
<pre><code> if([bluevia loadAccessTokenFromKeychain]) {
NSLog(@"Access Token loaded from Keychain");
} else {
NSLog(@"No Access Token found in Keychain");
}
</code></pre>
<p>And set the bluvia Sandbox property to “YES” (no access to the real network) or “NO” (access the real network, e.g. send real SMS)</p>
<pre><code> [bluevia setSandbox:"YES"];
</code></pre>
<p>Note: The BlueVia library assumes that your code implements the BlueViaDelegate protocol:</p>
<pre><code> @protocol BlueViaDelegate <NSObject>
- (void) gotRequestToken:(NSNumber*)status data:(NSDictionary*)data;
- (void) gotAccessToken:(NSNumber*)status data:(NSDictionary*)data;
- (void) sendSmsResponse:(NSNumber*)status data:(NSDictionary*)data;
- (void) trackSmsResponse:(NSNumber*)status data:(NSDictionary*)data;
- (void) locateHandsetResponse:(NSNumber*)status data:(NSDictionary*)data;
- (void) userContextResponse:(NSNumber*)status data:(NSDictionary*)data;
- (void) advertisingResponse:(NSNumber*)status data:(NSDictionary*)data;
@end
</code></pre>
<p>Each call to a bluevia method is asynchronous. The library will call (for both success and failure case) the respective protocol method in your code.</p>
<h3 id="oauthdance">oAuth Dance</h3>
<p>First step is to get a Request Token</p>
<pre><code> [bluevia fetchRequestToken:@"oob"];
</code></pre>
<p>You will receive the result in your implementation of “gotRequestToken”, e.g.:</p>
<pre><code> - (void) gotRequestToken:(NSNumber*)status data:(NSDictionary*)data {
if ([status longValue] == kBlueviaSuccess) {
NSString *authUrl = [data objectForKey:@"authorizationUrl"];
// do something with the authUrl, e.g. open Safari with it
} else {
NSLog(@"Error requesting Requrest Token ...");
}
}
</code></pre>
<p>After successful Authorisation the oAuth portal will provide the user with a verifier, e.g. “437456”. This verifier needs to handed over to the next call:</p>
<pre><code> NSString *verifier = @"437456";
[bluevia fetchAccessToken:verifier];
</code></pre>
<p>This time the result will be provided via “gotAccessToken” methos of the BlueViaDelegate protocol. Your implementation could look like this:</p>
<pre><code> - (void) gotAccessToken:(NSNumber*)status data:(NSDictionary*)data {
- (void) gotAccessToken:(NSNumber*)status data:(NSDictionary*)data {
[self defaultResponse:status data:data]; // optional
NSString *accessKey = [[data objectForKey:@"AccessKey"] retain]; // optional
NSString *accessSecret = [[data objectForKey:@"AccessSecret"] retain]; // optional
[bluevia saveAccessTokenToKeychain];
}
}
</code></pre>
<p>Here you could derive the Access Token Key and Secret, if you want to store it somewhere else or simply use the “saveAccessTokenToKeychain” method.</p>
<h3 id="sendsmsandtrackdelivery">Send SMS and track delivery</h3>
<pre><code> NSString *msisdns = @"447760xxxxxx,447763yyyyyy";
NSString *message = @"Hello World";
if ([msisdns isNotEqualTo:@""] && [message isNotEqualTo:@""]) {
NSNumber *smsId = [bluevia sendSMS:msisdns message:message];
}
</code></pre>
<p>Since the call is asynchronous, the routine gives back an id for the request. This id can be used in the “sendSmsResponse” method to associate a delivery URL (smsLocation) with its respective “send SMS ” call, e.g. :</p>
<pre><code> - (void) sendSmsResponse:(NSNumber*)status data:(NSDictionary*)data {
if ([status longValue] == kBlueviaSuccess) {
NSNumber* smsId = [data objectForKey:@"smsId"];
NSString* smsLocation = [data objectForKey:@"location"];
[trackSms setValue:smsLocation forKey:[NSString stringWithFormat:@"%@", smsId]];
}
}
</code></pre>
<p>Accordingly, to receive poll for the delivery notification, you would call (given that smsId is the one from above):</p>
<pre><code> NSString *location = [trackSms objectForKey:smsId];
if ([smsId isNotEqualTo:@""] && location) {
[bluevia trackSMS:location];
}
</code></pre>
<p>and the respective BlueViaDelegate method to implement is:</p>
<pre><code> - (void) trackSmsResponse:(NSNumber*)status data:(NSDictionary*)data;
</code></pre>
<p>Note: to use the real radio network, call:</p>
<pre><code> [bluevia setSandbox:"NO"];
</code></pre>
<p>This holds for all BlueVia calless below.</p>
<h3 id="usercontextapi">User Context API</h3>
<p>The actual call is:</p>
<pre><code> [bluevia userContext];
</code></pre>
<p>and the respective BlueViaDelegate method to implement is:</p>
<pre><code> - (void) userContextResponse:(NSNumber*)status data:(NSDictionary*)data;
</code></pre>
<h3 id="locationapi">Location API</h3>
<p>The actual call is:</p>
<pre><code> [bluevia locateHandset];
</code></pre>
<p>and the respective BlueViaDelegate method to implement is:</p>
<pre><code> - (void) locateHandsetResponse:(NSNumber*)status data:(NSDictionary*)data;
</code></pre>
<h3 id="advertisingapi3leggedoauth">Advertising API (3 legged oAuth)</h3>
<p>The actual call is:</p>
<pre><code> NSString *kwStr = @"sports,entertainment";
NSArray *kwList = nil;
if ([kwStr isNotEqualTo:@""]) {
kwList = [kwStr componentsSeparatedByString:@","];
}
[bluevia advertising3:textAds
userAgent:@""
keywordList:kwList
protectionPolicy:1];
</code></pre>
<p>and the respective BlueViaDelegate method to implement is:</p>
<pre><code> - (void) advertisingResponse:(NSNumber*)status data:(NSDictionary*)data;
</code></pre>
</body>
</html>