-
Notifications
You must be signed in to change notification settings - Fork 0
Expand file tree
/
Copy pathindex.html
More file actions
413 lines (363 loc) · 34.2 KB
/
Copy pathindex.html
File metadata and controls
413 lines (363 loc) · 34.2 KB
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
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
<!doctype html>
<html>
<head>
<meta charset="utf-8">
<meta content="IE=edge,chrome=1" http-equiv="X-UA-Compatible">
<meta name="viewport" content="width=device-width, initial-scale=1, maximum-scale=1">
<title>Glimr Docs</title>
<link href="stylesheets/screen.css" rel="stylesheet" type="text/css" media="screen" />
<link href="stylesheets/print.css" rel="stylesheet" type="text/css" media="print" />
<script src="https://ajax.googleapis.com/ajax/libs/jquery/1.11.0/jquery.min.js"></script>
<script src="javascripts/all.js" type="text/javascript"></script>
<script>
$(function() {
setupLanguages(["objective_c","java"]);
});
</script>
</head>
<body class="index">
<a href="#" id="nav-button">
<span>
NAV
<img src="images/navbar.png" />
</span>
</a>
<div class="tocify-wrapper">
<img src="images/logo.png" />
<div class="lang-selector">
<a href="#" data-language-name="objective_c">objective_c</a>
<a href="#" data-language-name="java">java</a>
</div>
<div class="search">
<input type="text" class="search" id="input-search" placeholder="Search">
</div>
<ul class="search-results"></ul>
<div id="toc">
</div>
<ul class="toc-footer">
<li><a href='http://www.glimr.io/contact.html'>Get in touch with Glimr</a></li>
</ul>
</div>
<div class="page-wrapper">
<div class="dark-box"></div>
<div class="content">
<h1 id='getting-started'>Getting started</h1>
<p>The following chapters explain most parts of the components that drive the Glimr platform. Feel free to contact us if anything is unclear.</p>
<p>This documentation touches briefly our customer dashboard and covers the integration of the SDK into your own application.</p>
<p>The mobile SDK basically allows other applications to perform those three tasks:</p>
<ul>
<li><p>Trigger events when entering / exiting Geo-fences or iBeacon regions</p></li>
<li><p>Present custom views and track actions when entering / exiting Geo-fences or iBeacon regions</p></li>
<li><p>Collect additional audience data of a device and receive device audience tags</p></li>
</ul>
<p>The SDK integration itself is very slim since almost everything is configured on the dashboard for dynamic customisation.
That means that account to access our dashboard is required in order to get started.</p>
<aside class="notice">
Please contact project@glimr.io if you haven’t access to our platform yet.
</aside>
<h1 id='dashboard'>Dashboard</h1>
<blockquote>
<p>After logging in you can find your API token under “SDK Download”</p>
</blockquote>
<p>The dashboard is the heart of our service. Here customers can customise the behaviour of the SDK and extract the data they are looking for. This configuration can be changed at any time.
It also supports multiple app bundles, multiple campaigns simultaniously, GPS based regions and iBeacon regions, creating audiences.
There is a lot to explore, when we set up new accounts, they are usually preconfigured to get started as quick as possible. If you have more questions about specific functionality of our dashboard, get in touch.</p>
<aside class="notice">
Access the dashboard: https://dashboard.katalysator.io
</aside>
<h1 id='sdk-integration'>SDK integration</h1>
<p>Apps basically need to be able to run location services in background with a working internet connection. Depending on the use case the SDK expects Bluetooth to be active. All communication with our servers is JSON and HTTPS and protected by an individual API_TOKEN.</p>
<p>We aim for continuous releases of our dashboard and the SDKs.</p>
<h2 id='requirements'>Requirements</h2><h3 id='ios'>iOS</h3>
<ul>
<li><p>The SDK requires the key <code class="prettyprint">NSLocationAlwaysUsageDescription</code> to be present in the <code class="prettyprint">.plist</code> file in order to register for location and iBeacon monitoring.
iBeacon monitoring does not require any additional permissions but Bluetooth must be active.</p></li>
<li><p>The SDK works on iOS 7.0 and up.</p></li>
<li><p>Linker flags <code class="prettyprint">-ObjC</code> and <code class="prettyprint">-all_load</code></p></li>
<li><p>Several iOS frameworks <code class="prettyprint">CoreLocation.framework</code>, <code class="prettyprint">CoreBluetooth.framework</code>, <code class="prettyprint">CoreTelephony.framework</code>, <code class="prettyprint">AdSupport.framework</code>, <code class="prettyprint">MediaPlayer.framework</code></p></li>
</ul>
<h3 id='android'>Android</h3>
<ul>
<li><p>The SDK works on Android 4.3+</p></li>
<li><p>It requires the following permissions, most of them are optional: <code class="prettyprint">INTERNET, BLUETOOTH, BLUETOOTH_ADMIN, ACCESS_WIFI_STATE, ACCESS_NETWORK_STATE, ACCESS_FINE_LOCATION or ACCESS_COURSE_LOCATION</code></p></li>
<li><p>Gson 2.2.4 comes pre-bundled with the library</p></li>
<li><p>Google Play Service 7.5.0. You can include parts of the library, Glimr SDK requires <code class="prettyprint">compile 'com.google.android.gms:play-services-ads:7.5.0'</code> and <code class="prettyprint">compile 'com.google.android.gms:play-services-location:7.5.0'</code></p></li>
</ul>
<h2 id='full-sample'>Full Sample</h2>
<blockquote>
<p>First setup a <code class="prettyprint">Configuration</code> object</p>
</blockquote>
<pre><code class="highlight objective_c"><span class="n">KATConfiguration</span> <span class="o">*</span><span class="n">config</span> <span class="o">=</span> <span class="p">[[</span><span class="n">KATConfiguration</span> <span class="nf">alloc</span><span class="p">]</span> <span class="nf">init</span><span class="p">];</span>
<span class="n">config</span><span class="p">.</span><span class="n">apiToken</span> <span class="o">=</span> <span class="p">[[</span><span class="n">NSUUID</span> <span class="nf">alloc</span><span class="p">]</span> <span class="nf">initWithUUIDString</span><span class="p">:</span><span class="s">@"YOUR_API_TOKEN"</span><span class="p">];</span>
<span class="n">config</span><span class="p">.</span><span class="n">handlerFilter</span> <span class="o">=</span> <span class="n">KATHandlerFilterData</span><span class="p">;</span>
<span class="n">config</span><span class="p">.</span><span class="n">allowCircularRegionMonitoring</span> <span class="o">=</span> <span class="nb">YES</span><span class="p">;</span>
<span class="n">config</span><span class="p">.</span><span class="n">allowAdvertisingIdentifierAccess</span> <span class="o">=</span> <span class="nb">YES</span><span class="p">;</span>
<span class="n">config</span><span class="p">.</span><span class="n">suppressBluetoothAccuracyAlert</span> <span class="o">=</span> <span class="nb">YES</span><span class="p">;</span>
<span class="n">config</span><span class="p">.</span><span class="n">askForNotificationPermission</span> <span class="o">=</span> <span class="nb">YES</span><span class="p">;</span>
</code></pre>
<pre><code class="highlight java"><span class="c1">// no configuration object for Android at this point</span>
</code></pre>
<blockquote>
<p>For region monitoring use the manager like this</p>
</blockquote>
<pre><code class="highlight objective_c"><span class="n">KATBeaconManager</span> <span class="o">*</span><span class="n">beaconManager</span> <span class="o">=</span> <span class="p">[[</span><span class="n">KATBeaconManager</span> <span class="nf">alloc</span><span class="p">]</span> <span class="nf">initWithConfiguration</span><span class="p">:</span><span class="n">config</span><span class="p">];</span>
<span class="p">[</span><span class="n">beaconManager</span> <span class="nf">startWithHandler</span><span class="p">:</span><span class="o">^</span><span class="p">(</span><span class="n">id</span> <span class="n">result</span><span class="p">,</span> <span class="n">BOOL</span> <span class="n">cached</span><span class="p">,</span> <span class="n">NSDate</span> <span class="o">*</span><span class="n">date</span><span class="p">,</span> <span class="n">NSError</span> <span class="o">*</span><span class="n">error</span><span class="p">)</span>
<span class="p">{</span>
<span class="n">NSLog</span><span class="p">(</span><span class="s">@"EVENT %@ %@"</span><span class="p">,</span> <span class="n">result</span><span class="p">,</span> <span class="n">date</span><span class="p">)</span><span class="err">;</span>
<span class="p">}];</span>
</code></pre>
<pre><code class="highlight java"><span class="c1">// init the manager</span>
<span class="n">mKatManager</span> <span class="o">=</span> <span class="n">KATManager</span><span class="o">.</span><span class="na">getInstance</span><span class="o">(</span><span class="k">this</span><span class="o">,</span> <span class="s">"YOUR_API_TOKEN"</span><span class="o">,</span> <span class="k">this</span><span class="o">);</span>
<span class="c1">// start monitoring for geofences and beacon ids configured on dashboard</span>
<span class="n">mKatManager</span><span class="o">.</span><span class="na">startMonitoring</span><span class="o">(</span><span class="k">this</span><span class="o">);</span>
<span class="c1">// implement the folling interface</span>
<span class="kd">public</span> <span class="kd">interface</span> <span class="nc">KATEvent</span> <span class="o">{</span>
<span class="kt">void</span> <span class="n">regionDataReceived</span><span class="o">(</span><span class="n">com</span><span class="o">.</span><span class="na">katalysator</span><span class="o">.</span><span class="na">sdk</span><span class="o">.</span><span class="na">engine</span><span class="o">.</span><span class="na">KATAssets</span> <span class="n">katAssets</span><span class="o">);</span>
<span class="kt">void</span> <span class="n">notificationShouldDisplay</span><span class="o">(</span><span class="n">com</span><span class="o">.</span><span class="na">katalysator</span><span class="o">.</span><span class="na">sdk</span><span class="o">.</span><span class="na">engine</span><span class="o">.</span><span class="na">KATAssets</span> <span class="n">katAssets</span><span class="o">,</span> <span class="n">java</span><span class="o">.</span><span class="na">lang</span><span class="o">.</span><span class="na">Class</span> <span class="n">aClass</span><span class="o">);</span>
<span class="kt">void</span> <span class="n">fullScreenImageShouldDisplay</span><span class="o">(</span><span class="n">java</span><span class="o">.</span><span class="na">lang</span><span class="o">.</span><span class="na">Class</span> <span class="n">aClass</span><span class="o">,</span> <span class="n">com</span><span class="o">.</span><span class="na">katalysator</span><span class="o">.</span><span class="na">sdk</span><span class="o">.</span><span class="na">engine</span><span class="o">.</span><span class="na">KATAssets</span> <span class="n">katAssets</span><span class="o">);</span>
<span class="o">}</span>
</code></pre>
<blockquote>
<p>The following show how to receive audience tags</p>
</blockquote>
<pre><code class="highlight objective_c"><span class="n">KATAudienceManager</span> <span class="o">*</span><span class="n">audienceManager</span> <span class="o">=</span> <span class="p">[[</span><span class="n">KATAudienceManager</span> <span class="nf">alloc</span><span class="p">]</span> <span class="nf">initWithApiToken</span><span class="p">:</span><span class="n">config</span><span class="p">.</span><span class="n">apiToken</span><span class="p">];</span>
<span class="p">[</span><span class="n">audienceManager</span> <span class="nf">audiencesAndGeotagsWithCompletion</span><span class="p">:</span><span class="o">^</span><span class="p">(</span><span class="n">NSDictionary</span> <span class="o">*</span><span class="n">audiences</span><span class="p">,</span> <span class="n">NSError</span> <span class="o">*</span><span class="n">error</span><span class="p">)</span>
<span class="p">{</span>
<span class="n">NSLog</span><span class="p">(</span><span class="s">@"AUDIENCES %@"</span><span class="p">,</span> <span class="n">audiences</span><span class="p">)</span><span class="err">;</span>
<span class="p">}];</span>
</code></pre>
<pre><code class="highlight java"><span class="c1">// load tags for the current device</span>
<span class="n">mKatManager</span><span class="o">.</span><span class="na">getAudiencesAndGeotags</span><span class="o">();</span>
<span class="c1">// implement the folling interface</span>
<span class="kd">public</span> <span class="kd">interface</span> <span class="nc">KATEvent</span> <span class="o">{</span>
<span class="kt">void</span> <span class="n">availableAudiencesUpdated</span><span class="o">(</span><span class="n">java</span><span class="o">.</span><span class="na">util</span><span class="o">.</span><span class="na">ArrayList</span><span class="o"><</span><span class="n">java</span><span class="o">.</span><span class="na">lang</span><span class="o">.</span><span class="na">String</span><span class="o">></span> <span class="n">arrayList</span><span class="o">);</span>
<span class="o">}</span>
</code></pre>
<p>You can find a complete code example to the right. </p>
<h3 id='ios'>iOS</h3>
<p>You have two options to integrate the iOS SDK. You can find the latest release on <a href="https://github.com/KatalysatorAB/BeaconSDK-iOS/releases">Github</a> or you use CocoaPods <code class="prettyprint">pod "KatalysatorSDK"</code> to add the latest stable version to your app.</p>
<p>Basically in order to listen to geo-fences and iBeacons you create a configuration object that you pass into the KATBeaconManager.
The managers provides the events in a block callback when calling <code class="prettyprint">startWithHandler</code>.</p>
<p>To receive audience tags from the dashboard, all you need is to create an instance of the <code class="prettyprint">KATAudienceManager</code> object with your API token and call <code class="prettyprint">audiencesAndGeotagsWithCompletion</code>.</p>
<h3 id='android'>Android</h3>
<p>You find the library on <a href="https://github.com/KatalysatorAB/BeaconSDK-Android">Github</a> as part of the sample implementation. The library itself is called <a href="https://github.com/KatalysatorAB/BeaconSDK-Android/tree/master/KATExampleApp/src/main/libs">katalysator_android_sdk.jar</a>. </p>
<p>Everything is managed by an <code class="prettyprint">KATManager</code> instance and the <code class="prettyprint">KATEvent</code> interface. Starting to monitor for regions is as simple as calling <code class="prettyprint">startMonitoring</code> and receiving audience tags can be done by calling <code class="prettyprint">getAudiencesAndGeotags</code>. </p>
<aside class="notice">
You must replace `YOUR_API_TOKEN` with your API key.
</aside>
<h1 id='region-monitoring'>Region monitoring</h1><h2 id='configuration-ios'>Configuration (iOS)</h2>
<blockquote>
<p>Sample for a recommended <code class="prettyprint">KATConfiguration</code> object</p>
</blockquote>
<pre><code class="highlight objective_c"><span class="n">KATConfiguration</span> <span class="o">*</span><span class="n">config</span> <span class="o">=</span> <span class="p">[[</span><span class="n">KATConfiguration</span> <span class="nf">alloc</span><span class="p">]</span> <span class="nf">init</span><span class="p">];</span>
<span class="n">config</span><span class="p">.</span><span class="n">apiToken</span> <span class="o">=</span> <span class="p">[[</span><span class="n">NSUUID</span> <span class="nf">alloc</span><span class="p">]</span> <span class="nf">initWithUUIDString</span><span class="p">:</span><span class="s">@"YOUR_API_TOKEN"</span><span class="p">];</span>
<span class="n">config</span><span class="p">.</span><span class="n">handlerFilter</span> <span class="o">=</span> <span class="n">KATHandlerFilterData</span><span class="p">;</span>
<span class="n">config</span><span class="p">.</span><span class="n">allowCircularRegionMonitoring</span> <span class="o">=</span> <span class="nb">YES</span><span class="p">;</span>
<span class="n">config</span><span class="p">.</span><span class="n">allowAdvertisingIdentifierAccess</span> <span class="o">=</span> <span class="nb">YES</span><span class="p">;</span>
<span class="n">config</span><span class="p">.</span><span class="n">suppressBluetoothAccuracyAlert</span> <span class="o">=</span> <span class="nb">YES</span><span class="p">;</span>
<span class="n">config</span><span class="p">.</span><span class="n">askForNotificationPermission</span> <span class="o">=</span> <span class="nb">YES</span><span class="p">;</span>
</code></pre>
<pre><code class="highlight java"><span class="c1">// no configuration object for Android at this point</span>
</code></pre>
<p>The <code class="prettyprint">KATConfiguration</code> object is necessary to initialise the region monitoring later on.</p>
<p>The options are:</p>
<table><thead>
<tr>
<th>Parameter</th>
<th>Default</th>
<th>Description</th>
</tr>
</thead><tbody>
<tr>
<td>apiToken</td>
<td>nil</td>
<td>Your API token, required for any dashboard interaction</td>
</tr>
<tr>
<td>regionToken</td>
<td>nil</td>
<td>Setting the regionToken to a UUID hardcodes the regions the app listens to. This is only recommended for development purpose</td>
</tr>
<tr>
<td>handlerFilter</td>
<td>KATHandlerFilterAll</td>
<td>Defines what type of information the block callback can receive (KATHandlerFilterAll, KATHandlerFilterAlert, KATHandlerFilterData)</td>
</tr>
<tr>
<td>suppressBluetoothAccuracyAlert</td>
<td>NO</td>
<td>This option will try it’s best to skip the bluetooth accuracy alert that iOS pops up by default</td>
</tr>
<tr>
<td>allowCircularRegionMonitoring</td>
<td>NO</td>
<td>This option allows geo-fences in addition to iBeacon region monitoring</td>
</tr>
<tr>
<td>allowAdvertisingIdentifierAccess</td>
<td>NO</td>
<td>If set the dashboard will receive information about the mobile advertisement identifier of the device</td>
</tr>
<tr>
<td>askForNotificationPermission</td>
<td>NO</td>
<td>If set the SDK will request <code class="prettyprint">requestAlwaysAuthorization</code> location permission. Please note that the <code class="prettyprint">NSLocationAlwaysUsageDescription</code> key must be present in the <code class="prettyprint">plist</code> of the app</td>
</tr>
</tbody></table>
<p>Calling the provided method signature <code class="prettyprint">- (NSArray *)configUpdate:(BOOL)force coordinate:(CLLocationCoordinate2D)coordinate completion:(KATUpdateConfigHandler)completion;</code> manually is not recommended as it will be called anyway when initialising the <code class="prettyprint">KATBeaconManager</code>.
This method will update the local configuration.</p>
<h2 id='geo-fences-and-ibeacons'>Geo-fences and iBeacons</h2>
<p>To initialise region monitoring all you need to do is to implement the sample code to the right.
Make sure this code is executed every time the app is started.
Calling it every time the app comes to foreground is fine as well.</p>
<aside class="notice">
You must replace `YOUR_API_TOKEN` with your API key.
</aside>
<blockquote>
<p>Full example to do region monitoring for iBeacons and geo-fences</p>
</blockquote>
<pre><code class="highlight objective_c"><span class="n">KATConfiguration</span> <span class="o">*</span><span class="n">config</span> <span class="o">=</span> <span class="p">[[</span><span class="n">KATConfiguration</span> <span class="nf">alloc</span><span class="p">]</span> <span class="nf">init</span><span class="p">];</span>
<span class="n">config</span><span class="p">.</span><span class="n">apiToken</span> <span class="o">=</span> <span class="p">[[</span><span class="n">NSUUID</span> <span class="nf">alloc</span><span class="p">]</span> <span class="nf">initWithUUIDString</span><span class="p">:</span><span class="s">@"YOUR_API_TOKEN"</span><span class="p">];</span>
<span class="n">config</span><span class="p">.</span><span class="n">handlerFilter</span> <span class="o">=</span> <span class="n">KATHandlerFilterData</span><span class="p">;</span>
<span class="n">config</span><span class="p">.</span><span class="n">allowCircularRegionMonitoring</span> <span class="o">=</span> <span class="nb">YES</span><span class="p">;</span>
<span class="n">config</span><span class="p">.</span><span class="n">allowAdvertisingIdentifierAccess</span> <span class="o">=</span> <span class="nb">YES</span><span class="p">;</span>
<span class="n">config</span><span class="p">.</span><span class="n">suppressBluetoothAccuracyAlert</span> <span class="o">=</span> <span class="nb">YES</span><span class="p">;</span>
<span class="n">config</span><span class="p">.</span><span class="n">askForNotificationPermission</span> <span class="o">=</span> <span class="nb">YES</span><span class="p">;</span>
<span class="n">KATBeaconManager</span> <span class="o">*</span><span class="n">beaconManager</span> <span class="o">=</span> <span class="p">[[</span><span class="n">KATBeaconManager</span> <span class="nf">alloc</span><span class="p">]</span> <span class="nf">initWithConfiguration</span><span class="p">:</span><span class="n">config</span><span class="p">];</span>
<span class="p">[</span><span class="n">beaconManager</span> <span class="nf">startWithHandler</span><span class="p">:</span><span class="o">^</span><span class="p">(</span><span class="n">id</span> <span class="n">result</span><span class="p">,</span> <span class="n">BOOL</span> <span class="n">cached</span><span class="p">,</span> <span class="n">NSDate</span> <span class="o">*</span><span class="n">date</span><span class="p">,</span> <span class="n">NSError</span> <span class="o">*</span><span class="n">error</span><span class="p">)</span>
<span class="p">{</span>
<span class="n">NSLog</span><span class="p">(</span><span class="s">@"EVENT %@ %@"</span><span class="p">,</span> <span class="n">result</span><span class="p">,</span> <span class="n">date</span><span class="p">)</span><span class="err">;</span>
<span class="p">}];</span>
</code></pre>
<pre><code class="highlight java"><span class="c1">// init the manager</span>
<span class="n">mKatManager</span> <span class="o">=</span> <span class="n">KATManager</span><span class="o">.</span><span class="na">getInstance</span><span class="o">(</span><span class="k">this</span><span class="o">,</span> <span class="s">"YOUR_API_TOKEN"</span><span class="o">,</span> <span class="k">this</span><span class="o">);</span>
<span class="c1">// start monitoring for geofences and beacon ids configured on dashboard</span>
<span class="n">mKatManager</span><span class="o">.</span><span class="na">startMonitoring</span><span class="o">(</span><span class="k">this</span><span class="o">);</span>
<span class="c1">// implement the folling interface</span>
<span class="kd">public</span> <span class="kd">interface</span> <span class="nc">KATEvent</span> <span class="o">{</span>
<span class="kt">void</span> <span class="n">regionDataReceived</span><span class="o">(</span><span class="n">com</span><span class="o">.</span><span class="na">katalysator</span><span class="o">.</span><span class="na">sdk</span><span class="o">.</span><span class="na">engine</span><span class="o">.</span><span class="na">KATAssets</span> <span class="n">katAssets</span><span class="o">);</span>
<span class="kt">void</span> <span class="n">notificationShouldDisplay</span><span class="o">(</span><span class="n">com</span><span class="o">.</span><span class="na">katalysator</span><span class="o">.</span><span class="na">sdk</span><span class="o">.</span><span class="na">engine</span><span class="o">.</span><span class="na">KATAssets</span> <span class="n">katAssets</span><span class="o">,</span> <span class="n">java</span><span class="o">.</span><span class="na">lang</span><span class="o">.</span><span class="na">Class</span> <span class="n">aClass</span><span class="o">);</span>
<span class="kt">void</span> <span class="n">fullScreenImageShouldDisplay</span><span class="o">(</span><span class="n">java</span><span class="o">.</span><span class="na">lang</span><span class="o">.</span><span class="na">Class</span> <span class="n">aClass</span><span class="o">,</span> <span class="n">com</span><span class="o">.</span><span class="na">katalysator</span><span class="o">.</span><span class="na">sdk</span><span class="o">.</span><span class="na">engine</span><span class="o">.</span><span class="na">KATAssets</span> <span class="n">katAssets</span><span class="o">);</span>
<span class="o">}</span>
</code></pre>
<p>Based on the dashboard configuration the callback will receive the response for a configured campaign.
The app can use this information further and present views, track events or perform other actions.</p>
<h3 id='ios'>iOS</h3>
<p>The <code class="prettyprint">KATAdvertHandler</code> block of <code class="prettyprint">startWithHandler</code> brings along the following parameters:</p>
<table><thead>
<tr>
<th>Parameter</th>
<th>Default</th>
<th>Description</th>
</tr>
</thead><tbody>
<tr>
<td>result</td>
<td>nil</td>
<td>Depending on the <code class="prettyprint">handlerFilter</code> this might be a <code class="prettyprint">NSDictionary</code> or a <code class="prettyprint">UILocalNotification</code> object</td>
</tr>
<tr>
<td>cached</td>
<td>NO</td>
<td>If set you know the user received this event while being in background or “closed down”</td>
</tr>
<tr>
<td>date</td>
<td>nil</td>
<td>The date the event was triggered</td>
</tr>
<tr>
<td>error</td>
<td>nil</td>
<td>A possible error that occurred when communicating with Glimr servers</td>
</tr>
</tbody></table>
<h3 id='android'>Android</h3>
<p>The parameter of <code class="prettyprint">regionDataReceived</code> is an instance of <code class="prettyprint">KATAssets</code> which represents the possible values that can be configured on the dashboard.
If the campaign is configured to be of type <code class="prettyprint">view</code> you might want to look at the <code class="prettyprint">fullScreenImageShouldDisplay</code> method of the Glimr sample application on Github. The same goes for <code class="prettyprint">notificationShouldDisplay</code>. Please note that <code class="prettyprint">regionDataReceived</code> gets called in all cases.</p>
<h2 id='debugging-ios'>Debugging (iOS)</h2>
<p>The SDK provides a few tweaks to help developer debug the SDK integration.</p>
<p><code class="prettyprint">triggerWithHandler</code> will perform a callback immediately before contacting the Glimr servers showing the payload that will be send to the dashboard.</p>
<blockquote>
<p>Sample <code class="prettyprint">triggerWithHandler</code></p>
</blockquote>
<pre><code class="highlight objective_c"><span class="p">[</span><span class="n">beaconManager</span> <span class="nf">triggerWithHandler</span><span class="p">:</span><span class="o">^</span><span class="p">(</span><span class="n">NSDictionary</span> <span class="o">*</span><span class="n">requestDict</span><span class="p">)</span>
<span class="p">{</span>
<span class="n">NSLog</span><span class="p">(</span><span class="s">@"TRIGGER %@"</span><span class="p">,</span> <span class="n">requestDict</span><span class="p">)</span><span class="err">;</span>
<span class="p">}];</span>
</code></pre>
<pre><code class="highlight java"><span class="c1">// no additional logging for Android at this point, logs written to standard log</span>
</code></pre>
<blockquote>
<p>Sample <code class="prettyprint">debugWithHandler</code></p>
</blockquote>
<p><code class="prettyprint">debugWithHandler</code> allows logging of different events that happen under the hood of the SDK.</p>
<pre><code class="highlight objective_c"><span class="p">[</span><span class="n">beaconManager</span> <span class="nf">debugWithHandler</span><span class="p">:</span><span class="o">^</span><span class="p">(</span><span class="n">id</span> <span class="n">result</span><span class="p">)</span>
<span class="p">{</span>
<span class="n">NSLog</span><span class="p">(</span><span class="s">@"DEBUG %@"</span><span class="p">,</span> <span class="n">result</span><span class="p">)</span><span class="err">;</span>
<span class="p">}];</span>
</code></pre>
<pre><code class="highlight java"><span class="c1">// no additional logging for Android at this point, logs written to standard log</span>
</code></pre>
<p>Thos methods are completely optional and usually for debugging purposes only.</p>
<h1 id='audiences'>Audiences</h1>
<p>Another functionality of the SDK is to collect additional data and read the assign audience tags defined on the Glimr dashboard.
The dashboard allows to create audiences based on offline behaviour of a device gathered from from iBeacon regions and geo-fences.
Applications can use the result of the mined data and use it i.e. to feed ad systems with additional keywords about the deivce/user.</p>
<h2 id='collect-data'>Collect data</h2>
<p>To collect additional data, use the example to the right. The parameter needs to needs to be of a key-value dictionary and all combinations must but JSON serializable.</p>
<blockquote>
<p>Full example for collecting more information</p>
</blockquote>
<pre><code class="highlight objective_c"><span class="n">KATAudienceManager</span> <span class="o">*</span><span class="n">audienceManager</span> <span class="o">=</span> <span class="p">[[</span><span class="n">KATAudienceManager</span> <span class="nf">alloc</span><span class="p">]</span> <span class="nf">initWithApiToken</span><span class="p">:</span><span class="s">@"YOUR_API_TOKEN"</span><span class="p">];</span>
<span class="p">[</span><span class="n">audienceManager</span> <span class="nf">collect</span><span class="p">:</span><span class="err">@</span><span class="p">{</span> <span class="s">@"userId"</span> <span class="o">:</span> <span class="s">@"sven@glimr.io"</span> <span class="p">}];</span>
</code></pre>
<pre><code class="highlight java"><span class="c1">// init the manager</span>
<span class="n">mKatManager</span> <span class="o">=</span> <span class="n">KATManager</span><span class="o">.</span><span class="na">getInstance</span><span class="o">(</span><span class="k">this</span><span class="o">,</span> <span class="s">"YOU_API_TOKEN"</span><span class="o">,</span> <span class="k">this</span><span class="o">);</span>
<span class="c1">// option to add aditional information about a device</span>
<span class="n">HashMap</span> <span class="n">keyValue</span> <span class="o">=</span> <span class="k">new</span> <span class="n">HashMap</span><span class="o">();</span>
<span class="n">keyValue</span><span class="o">.</span><span class="na">put</span><span class="o">(</span><span class="s">"username"</span><span class="o">,</span> <span class="s">"sven@glimr.io"</span><span class="o">);</span>
<span class="n">mKatManager</span><span class="o">.</span><span class="na">collect</span><span class="o">(</span><span class="n">keyValue</span><span class="o">);</span>
</code></pre>
<aside class="notice">
You must replace `YOUR_API_TOKEN` with your API key.
</aside>
<h2 id='get-device-tags'>Get device tags</h2>
<p>The SDK allows developers to receive the tags assigned to a device. The example shows a full example of that.
Please note that audiences are generated every ten minutes at the moment. Depending on the time passed by the call will not always reach out to the servers but instead return a local version of the result.
In general this function should be called whenever the app comes to foreground in order to receive the latest tags for a device.</p>
<h3 id='ios'>iOS</h3>
<p>The completion block contains a <code class="prettyprint">NSDictionary</code> wit the key <code class="prettyprint">tags</code>, which represents an array of assigned tags for the device.</p>
<h3 id='android'>Android</h3>
<p>The interface method <code class="prettyprint">availableAudiencesUpdated</code> gets called with an array of strings representing the assigned tags.</p>
<blockquote>
<p>Full example for reading tags assigned to the current device</p>
</blockquote>
<pre><code class="highlight objective_c"><span class="n">KATAudienceManager</span> <span class="o">*</span><span class="n">audienceManager</span> <span class="o">=</span> <span class="p">[[</span><span class="n">KATAudienceManager</span> <span class="nf">alloc</span><span class="p">]</span> <span class="nf">initWithApiToken</span><span class="p">:</span><span class="s">@"YOUR_API_TOKEN"</span><span class="p">];</span>
<span class="p">[</span><span class="n">audienceManager</span> <span class="nf">audiencesAndGeotagsWithCompletion</span><span class="p">:</span><span class="o">^</span><span class="p">(</span><span class="n">NSDictionary</span> <span class="o">*</span><span class="n">audiences</span><span class="p">,</span> <span class="n">NSError</span> <span class="o">*</span><span class="n">error</span><span class="p">)</span>
<span class="p">{</span>
<span class="n">NSLog</span><span class="p">(</span><span class="s">@"AUDIENCES %@"</span><span class="p">,</span> <span class="n">audiences</span><span class="p">)</span><span class="err">;</span>
<span class="p">}];</span>
</code></pre>
<pre><code class="highlight java"><span class="c1">// init the manager</span>
<span class="n">mKatManager</span> <span class="o">=</span> <span class="n">KATManager</span><span class="o">.</span><span class="na">getInstance</span><span class="o">(</span><span class="k">this</span><span class="o">,</span> <span class="s">"YOUR_API_TOKEN"</span><span class="o">,</span> <span class="k">this</span><span class="o">);</span>
<span class="c1">// load tags for the current device</span>
<span class="n">mKatManager</span><span class="o">.</span><span class="na">getAudiencesAndGeotags</span><span class="o">();</span>
<span class="c1">// implement the folling interface</span>
<span class="kd">public</span> <span class="kd">interface</span> <span class="nc">KATEvent</span> <span class="o">{</span>
<span class="kt">void</span> <span class="n">availableAudiencesUpdated</span><span class="o">(</span><span class="n">java</span><span class="o">.</span><span class="na">util</span><span class="o">.</span><span class="na">ArrayList</span><span class="o"><</span><span class="n">java</span><span class="o">.</span><span class="na">lang</span><span class="o">.</span><span class="na">String</span><span class="o">></span> <span class="n">arrayList</span><span class="o">);</span>
<span class="o">}</span>
</code></pre>
<aside class="notice">
You must replace `YOUR_API_TOKEN` with your API key.
</aside>
</div>
<div class="dark-box">
<div class="lang-selector">
<a href="#" data-language-name="objective_c">objective_c</a>
<a href="#" data-language-name="java">java</a>
</div>
</div>
</div>
</body>
</html>