Android SDK integration

= 1. Overview =

MobigateSDK is a tool for gathering users phone data and event tracking. We have developed an SDK that is highly robust, secure, lightweight and very simple to embed.

8

You can track installs, updates and sessions and also track additional in-app events beyond app installs .

9

10

The MobigateSDK is compatible with Android OS version 4.0 and above.

11

12

Chapters 2 and 3 are MANDATORY to implement BASIC SDK integration. Tracking in-app events chapter is HIGHLY RECOMMENDED to implement. The rest of the described features are OPTIONAL to implement, although some of them may be necessary for you, depending on your app's business logic.

13

14

= 2. Adding library to project =

15

16

**Click [[here>>https://github.com/mobigatesdk/SamplesWithMobigateSDK]] to download sample app integration source code.**

== Step 1 ==

To add the library into Android Studio with Gradle build system, add to your top-level build.gradle file:

repositories {

maven {

url "https://repository.spicymobile.pl/repository/spicymobilerelease/"

}

...

}

== Step 2 ==

Then add the implementation dependency to your module build.gradle file (you can check the latest repository version [[here>>https://repository.spicymobile.pl/#browse/pl.spicymobile.mobigate.sdk]]:

dependencies {

implementation 'pl.spicymobile.mobigate.sdk:mobigate-sdk:1.x'

...

}

= 3. SDK Initialization =

43

44

In order to obtain "API_KEY", contact us by going to the "Contact" tab.

45

46

To initialize the SDK, add the following code in your Application onCreate() function:

47

48

49

public class MyApplication extends Application {

50

@Override

51

public void onCreate() {

52

super.onCreate();

53

/*minimum library configuration*/

54

SDK sdk = new MobigateSDK.Builder(getApplicationContext(),"Api_key").build();

55

/*start data gather*/

sdk.startService();

}

}

{{{

}}}

= 4. Tracking in-app events =

== 4.1 Overview ==

In-App Events provide insight on what is happening in your app. It is recommended to take the time and define the events you would like to measure.

70

71

An event consists of two fields that you (% style="display:none" %) (%%)can use to describe a user's interaction with your app content:

72

73

(% class="table-bordered" %)

74

|(% style="background-color:powderblue; width:200px" %)**Field name**|(% style="background-color:powderblue; width:200px" %)**Type**|(% style="background-color:powderblue; width:200px" %)**Required**|(% style="background-color:powderblue; width:200px" %)**Description**

75

|(% style="width:200px" %)Category|(% style="width:200px" %)String/EventCategory|(% style="width:200px" %)yes|(% style="width:200px" %)Event category

76

|(% style="width:200px" %)Parameter|(% style="width:200px" %)String/EventParameter|(% style="width:200px" %)no|(% style="width:200px" %)Event parameter.

77

There can be more than one

78

79

You can use any event category or parameter string of your choice. However, our SDK contains recommended event categories and parameters via enumerations (see [[Event categories>>doc:||anchor="H4.3Eventcategories"]] and [[Event parameters>>doc:||anchor="H4.4Eventparameters"]]).

80

81

== 4.2 Implementation ==

82

83

Tracking in-app events is performed by two methods:

84

85

86

MobigateSDK.get().trackEvent(new Category.Builder(EventCategory.ADD_PAYMENT_INFO)

87

.setParameter(EventParameter.CITY,"warszawa")

88

.setParameter(EventParameter.CURRENCY, "PLN")

89

.setParameter("UserChoiceParameterName", 12345)

90

.build())

91

MobigateSDK.get().trackAppInstall(long timestamp) //with event timestamp parameter

92

93

94

== 4.3 Event categories ==

95

96

The following section describes the recommended structure of each event category. In-app events categories are defined as part of the EventCategory enumeration class.

97

98

{{showhide id="1" showmessage="LEVEL_ACCOMPLISHED" hidemessage="LEVEL_ACCOMPLISHED" effect="slide" effectduration="0.3" style="border-radius: 5px; border: 1px solid powderblue; padding: 7px 7px 7px 30px; margin: 0px"}}

99

100

\\**Description:** Track accomplished game level achievement

101

**Event category:** EventCategory.LEVEL_ACCOMPLISHED

102

**Recommended parameters:** LEVEL, SCORE

103

104

105

{{showhide id="2" showmessage="ADD_PAYMENT_INFO" hidemessage="ADD_PAYMENT_INFO" effect="slide" effectduration="0.3" style="border-radius: 5px; border: 1px solid powderblue; padding: 7px 7px 7px 30px; margin: -1px 0px 0px 0px"}}

106

107

\\**Description:** Track payment info

108

**Event category:** EventCategory.ADD_PAYMENT_INFO

109

**Recommended parameters:** SUCCESS

110

111

112

{{showhide id="3" showmessage="ADD_TO_BASKET" hidemessage="ADD_TO_BASKET" effect="slide" effectduration="0.3" style="border-radius: 5px; border: 1px solid powderblue; padding: 7px 7px 7px 30px; margin: -1px 0px 0px 0px"}}

113

114

\\**Description:** Track add item to basket

115

**Event category:** EventCategory.ADD_TO_BASKET

116

**Recommended parameters:** PRICE, CONTENT_TYPE, CONTENT_ID, CONTENT, CURRENCY, QUANTITY

117

118

119

{{showhide id="4" showmessage="REMOVED_FROM_BASKET" hidemessage="REMOVED_FROM_BASKET" effect="slide" effectduration="0.3" style="border-radius: 5px; border: 1px solid powderblue; padding: 7px 7px 7px 30px; margin: -1px 0px 0px 0px"}}

120

121

\\**Description:** Track removed item from basket

122

**Event category:** EventCategory.REMOVED_FROM_BASKET

123

**Recommended parameters:** PRICE, CONTENT_TYPE, CONTENT_ID, CONTENT, CURRENCY, QUANTITY

124

125

126

{{showhide id="5" showmessage="ADD_TO_WISH_LIST" hidemessage="ADD_TO_WISH_LIST" effect="slide" effectduration="0.3" style="border-radius: 5px; border: 1px solid powderblue; padding: 7px 7px 7px 30px; margin: -1px 0px 0px 0px"}}

127

128

\\**Description:** Track add item to wish list

129

**Event category:** EventCategory.ADD_TO_WISH_LIST

130

**Recommended parameters:** PRICE, CONTENT_TYPE, CONTENT_ID, CONTENT, CURRENCY, QUANTITY

131

132

133

{{showhide id="6" showmessage="REGISTRATION" hidemessage="REGISTRATION" effect="slide" effectduration="0.3" style="border-radius: 5px; border: 1px solid powderblue; padding: 7px 7px 7px 30px; margin: -1px 0px 0px 0px"}}

134

135

\\**Description:** Track registration

136

**Event category:** EventCategory.REGISTRATION

137

**Recommended parameters:** REGISTRATION_METHOD

138

139

140

{{showhide id="7" showmessage="TUTORIAL_COMPLETION" hidemessage="TUTORIAL_COMPLETION" effect="slide" effectduration="0.3" style="border-radius: 5px; border: 1px solid powderblue; padding: 7px 7px 7px 30px; margin: -1px 0px 0px 0px"}}

141

142

\\**Description:** Track tutorial completion

143

**Event category:** EventCategory.TUTORIAL_COMPLETION

144

**Recommended parameters:** SUCCESS, CONTENT, CONTENT_ID

145

146

147

{{showhide id="8" showmessage="TRIGGER_CHECKOUT" hidemessage="TRIGGER_CHECKOUT" effect="slide" effectduration="0.3" style="border-radius: 5px; border: 1px solid powderblue; padding: 7px 7px 7px 30px; margin: -1px 0px 0px 0px"}}

148

149

\\**Description:** Track triggered checkout

150

**Event category:** EventCategory.TRIGGER_CHECKOUT

151

**Recommended parameters:** PROCE, CONTENT_TYPE, CONTENT_ID, CONTENT, QUANTITY, PAYMENT_INFO_AVAILABLE, CURRENCY

152

153

154

{{showhide id="9" showmessage="PURCHASE" hidemessage="PURCHASE" effect="slide" effectduration="0.3" style="border-radius: 5px; border: 1px solid powderblue; padding: 7px 7px 7px 30px; margin: -1px 0px 0px 0px"}}

155

156

\\**Description:** Track purchased item

157

**Event category:** EventCategory.PURCHASE

158

**Recommended parameters:** REVENUE, CONTENT_TYPE, CONTENT_ID, CONTENT, PRICE, QUANTITY, CURRENCY, ORDER_ID

159

160

161

{{showhide id="10" showmessage="SUBSCRIBE" hidemessage="SUBSCRIBE" effect="slide" effectduration="0.3" style="border-radius: 5px; border: 1px solid powderblue; padding: 7px 7px 7px 30px; margin: -1px 0px 0px 0px"}}

162

163

\\**Description:** Track subscription purchase

164

**Event category:** EventCategory.SUBSCRIBE

165

**Recommended parameters:** REVENUE, CURRENCY

166

167

168

{{showhide id="11" showmessage="BEGIN_TRIAL" hidemessage="BEGIN_TRIAL" effect="slide" effectduration="0.3" style="border-radius: 5px; border: 1px solid powderblue; padding: 7px 7px 7px 30px; margin: -1px 0px 0px 0px"}}

169

170

\\**Description:** Track begin trail of product

171

**Event category:** EventCategory.BEGIN_TRIAL

172

**Recommended parameters:** PRICE, CURRENCY

173

174

175

{{showhide id="12" showmessage="RATE" hidemessage="RATE" effect="slide" effectduration="0.3" style="border-radius: 5px; border: 1px solid powderblue; padding: 7px 7px 7px 30px; margin: -1px 0px 0px 0px"}}

176

177

\\**Description:** Track app/item rate

178

**Event category:** EventCategory.RATE

179

**Recommended parameters:** RATING_VALUE, CONTENT_TYPE, CONTENT_ID, CONTENT, MAX_RATING_VALUE

180

181

182

{{showhide id="13" showmessage="SEARCH" hidemessage="SEARCH" effect="slide" effectduration="0.3" style="border-radius: 5px; border: 1px solid powderblue; padding: 7px 7px 7px 30px; margin: -1px 0px 0px 0px"}}

183

\\**Description:** Track search event

184

**Event category:** EventCategory.SEARCH

185

**Recommended parameters:** CONTENT_TYPE, SEARCH_STRING, SUCCESS

186

187

188

{{showhide id="14" showmessage="USED_CREDIT" hidemessage="USED_CREDIT" effect="slide" effectduration="0.3" style="border-radius: 5px; border: 1px solid powderblue; padding: 7px 7px 7px 30px; margin: -1px 0px 0px 0px"}}

189

\\**Description:** Track use of credit

190

**Event category:** EventCategory.USED_CREDIT

191

**Recommended parameters:** PRICE, CONTENT_TYPE, CONTENT_ID, CONTENT

192

193

194

{{showhide id="15" showmessage="UNLOCKED_ACHIEVEMENT" hidemessage="UNLOCKED_ACHIEVEMENT" effect="slide" effectduration="0.3" style="border-radius: 5px; border: 1px solid powderblue; padding: 7px 7px 7px 30px; margin: -1px 0px 0px 0px"}}

195

\\**Description:** Track achievement unlock

196

**Event category:** EventCategory.UNLOCKED_ACHIEVEMENT

197

**Recommended parameters:** DESCRIPTION

198

199

200

{{showhide id="16" showmessage="VIEW_CONTENT" hidemessage="VIEW_CONTENT" effect="slide" effectduration="0.3" style="border-radius: 5px; border: 1px solid powderblue; padding: 7px 7px 7px 30px; margin: -1px 0px 0px 0px"}}

201

\\**Description:** Track content view event

202

**Event category:** EventCategory.VIEW_CONTENT

203

**Recommended parameters:** PRICE, CONTENT_TYPE, CONTENT_ID, CONTENT, CURRENCY

204

205

206

{{showhide id="17" showmessage="VIEW_LIST" hidemessage="VIEW_LIST" effect="slide" effectduration="0.3" style="border-radius: 5px; border: 1px solid powderblue; padding: 7px 7px 7px 30px; margin: -1px 0px 0px 0px"}}

207

\\**Description:** Track list event

208

**Event category:** EventCategory.VIEW_LIST

209

**Recommended parameters:** CONTENT_TYPE, CONTENT_LIST

210

211

212

{{showhide id="18" showmessage="CLICK_AD" hidemessage="CLICK_AD" effect="slide" effectduration="0.3" style="border-radius: 5px; border: 1px solid powderblue; padding: 7px 7px 7px 30px; margin: -1px 0px 0px 0px"}}

213

\\**Description:** Track ad click

214

**Event category:** EventCategory.CLICK_AD

215

**Recommended parameters:** CONTENT_TYPE, CONTENT_ID

216

217

218

{{showhide id="19" showmessage="VIEW_AD" hidemessage="VIEW_AD" effect="slide" effectduration="0.3" style="border-radius: 5px; border: 1px solid powderblue; padding: 7px 7px 7px 30px; margin: -1px 0px 0px 0px"}}

219

\\**Description:** Track view ad

220

**Event category:** EventCategory.VIEW_AD

221

**Recommended parameters:** CONTENT_TYPE, CONTENT_ID

222

223

224

{{showhide id="20" showmessage="EVENT_BOOKING" hidemessage="EVENT_BOOKING" effect="slide" effectduration="0.3" style="border-radius: 5px; border: 1px solid powderblue; padding: 7px 7px 7px 30px; margin: -1px 0px 0px 0px"}}

225

\\**Description:** Track booking event

226

**Event category:** EventCategory.EVENT_BOOKING

227

**Recommended parameters:** REVENUE, DESTINATION_A, DESTINATION_B, CLASS, DESCRIPTION, CUSTOMER_USER_ID, CONTENT_TYPE, CONTENT_ID, DATE_A, DATE_B

228

229

230

{{showhide id="21" showmessage="SHARE" hidemessage="SHARE" effect="slide" effectduration="0.3" style="border-radius: 5px; border: 1px solid powderblue; padding: 7px 7px 7px 30px; margin: -1px 0px 0px 0px"}}

231

\\**Description:** Track share event

232

**Event category:** EventCategory.SHARE

233

**Recommended parameters:** DESCRIPTION

234

235

236

{{showhide id="22" showmessage="INVITE" hidemessage="INVITE" effect="slide" effectduration="0.3" style="border-radius: 5px; border: 1px solid powderblue; padding: 7px 7px 7px 30px; margin: -1px 0px 0px 0px"}}

237

\\**Description:** Track social invite event

238

**Event category:** EventCategory.INVITE

239

**Recommended parameters:** NONE

240

241

242

{{showhide id="23" showmessage="LOGIN" hidemessage="LOGIN" effect="slide" effectduration="0.3" style="border-radius: 5px; border: 1px solid powderblue; padding: 7px 7px 7px 30px; margin: -1px 0px 0px 0px"}}

243

\\**Description:** Track user login event

244

**Event category:** EventCategory.LOGIN

245

**Recommended parameters:** NONE

246

247

248

{{showhide id="24" showmessage="EVENT_RETURN" hidemessage="EVENT_RETURN" effect="slide" effectduration="0.3" style="border-radius: 5px; border: 1px solid powderblue; padding: 7px 7px 7px 30px; margin: -1px 0px 0px 0px"}}

249

\\**Description:** Track re engagement event

250

**Event category:** EventCategory.EVENT_RETURN

251

**Recommended parameters:** NONE

252

253

254

{{showhide id="25" showmessage="OPENED_PUSH_NOTIFICATION" hidemessage="OPENED_PUSH_NOTIFICATION" effect="slide" effectduration="0.3" style="border-radius: 5px; border: 1px solid powderblue; padding: 7px 7px 7px 30px; margin: -1px 0px 0px 0px"}}

255

\\**Description:** Track user opened push notification

256

**Event category:** EventCategory.OPENED_PUSH_NOTIFICATION

257

**Recommended parameters:** NONE

258

259

260

{{showhide id="26" showmessage="UPDATE" hidemessage="UPDATE" effect="slide" effectduration="0.3" style="border-radius: 5px; border: 1px solid powderblue; padding: 7px 7px 7px 30px; margin: -1px 0px 0px 0px"}}

261

\\**Description:** Track update event

262

**Event category:** EventCategory.UPDATE

263

**Recommended parameters:** CONTENT_ID

== 4.4 Event parameters ==

268

269

In addition each category that is passed with event may have optional parameters defined as part of the EventParameter enum class, or custom defined as String. Below is a list of recommended parameters.

270

271

(% class="table-bordered" %)

272

|(% style="background-color:powderblue; width:200px" %)**Parameter enum**|(% style="background-color:powderblue; width:200px" %)**Recommended value**

273

|(% style="width:200px" %)EventParameter.REVENUE|(% style="width:200px" %)FLoat

274

|(% style="width:200px" %)EventParameter.PRICE|(% style="width:200px" %)Float

275

|(% style="width:200px" %)EventParameter.LEVEL|(% style="width:200px" %)Integer

276

|(% style="width:200px" %)EventParameter.SUCCESS|(% style="width:200px" %)Boolean

277

|(% style="width:200px" %)EventParameter.CONTENT_TYPE|(% style="width:200px" %)String

278

|(% style="width:200px" %)EventParameter.CONTENT_LIST|(% style="width:200px" %)Array of strings

279

|(% style="width:200px" %)EventParameter.CONTENT_ID|(% style="width:200px" %)String

280

|(% style="width:200px" %)EventParameter.CURRENCY|(% style="width:200px" %)String

281

|(% style="width:200px" %)EventParameter.REGISTRATION_METHOD|(% style="width:200px" %)String

282

|(% style="width:200px" %)EventParameter.QUANTITY|(% style="width:200px" %)Integer

283

|(% style="width:200px" %)EventParameter.PAYMENT_INFO_AVAILABLE|(% style="width:200px" %)Boolean

284

|(% style="width:200px" %)EventParameter.RATING_VALUE|(% style="width:200px" %)Float

285

|(% style="width:200px" %)EventParameter.MAX_RATING_VALUE|(% style="width:200px" %)Float

286

|(% style="width:200px" %)EventParameter.SEARCH_STRING|(% style="width:200px" %)String

287

|(% style="width:200px" %)EventParameter.DESCRIPTION|(% style="width:200px" %)String

288

|(% style="width:200px" %)EventParameter.SCORE|(% style="width:200px" %)Integer

289

|(% style="width:200px" %)EventParameter.DESTINATION_A|(% style="width:200px" %)String

290

|(% style="width:200px" %)EventParameter.DESTINATION_B|(% style="width:200px" %)String

291

|(% style="width:200px" %)EventParameter.CLASS|(% style="width:200px" %)String

292

|(% style="width:200px" %)EventParameter.DATE_A|(% style="width:200px" %)String

293

|(% style="width:200px" %)EventParameter.DATE_B|(% style="width:200px" %)String

294

|(% style="width:200px" %)EventParameter.EVENT_START|(% style="width:200px" %)Unixtime

295

|(% style="width:200px" %)EventParameter.EVENT_END|(% style="width:200px" %)Unixtime

296

|(% style="width:200px" %)EventParameter.LATITUDE|(% style="width:200px" %)Double

297

|(% style="width:200px" %)EventParameter.LONGITUDE|(% style="width:200px" %)Double

298

|(% style="width:200px" %)EventParameter.CUSTOMER_USER_ID|(% style="width:200px" %)String

299

|(% style="width:200px" %)EventParameter.CUSTOMER_SEGMENT|(% style="width:200px" %)String

300

|(% style="width:200px" %)EventParameter.VALIDATED|(% style="width:200px" %)String

301

|(% style="width:200px" %)EventParameter.RECEIPT_ID|(% style="width:200px" %)String

302

|(% style="width:200px" %)EventParameter.ORDER_ID|(% style="width:200px" %)String

303

|(% style="width:200px" %)EventParameter.TUTORIAL_ID|(% style="width:200px" %)String

304

|(% style="width:200px" %)EventParameter.ACHIEVEMENT_ID|(% style="width:200px" %)String

305

|(% style="width:200px" %)EventParameter.VIRTUAL_CURRENCY_NAME|(% style="width:200px" %)String

306

|(% style="width:200px" %)EventParameter.DEEP_LINK|(% style="width:200px" %)String

307

|(% style="width:200px" %)EventParameter.OLD_VERSION|(% style="width:200px" %)String

308

|(% style="width:200px" %)EventParameter.NEW_VERSION|(% style="width:200px" %)String

309

|(% style="width:200px" %)EventParameter.REVIEW_TEXT|(% style="width:200px" %)String

310

|(% style="width:200px" %)EventParameter.COUPON_CODE|(% style="width:200px" %)String

311

|(% style="width:200px" %)EventParameter.DEPARTING_DEPARTURE_DATE|(% style="width:200px" %)String

312

|(% style="width:200px" %)EventParameter.RETURNING_DEPARTURE_DATE|(% style="width:200px" %)String

313

|(% style="width:200px" %)EventParameter.DESTINATION_LIST|(% style="width:200px" %)String[]

314

|(% style="width:200px" %)EventParameter.CITY|(% style="width:200px" %)String

315

|(% style="width:200px" %)EventParameter.REGION|(% style="width:200px" %)String

316

|(% style="width:200px" %)EventParameter.COUNTRY|(% style="width:200px" %)String

317

|(% style="width:200px" %)EventParameter.DEPARTING_ARRIVAL_DATE|(% style="width:200px" %)String

318

|(% style="width:200px" %)EventParameter.RETURNING_ARRIVAL_DATE|(% style="width:200px" %)String

319

|(% style="width:200px" %)EventParameter.SUGGESTED_DESTINATIONS|(% style="width:200px" %)String[]

320

|(% style="width:200px" %)EventParameter.TRAVEL_START|(% style="width:200px" %)String

321

|(% style="width:200px" %)EventParameter.TRAVEL_END|(% style="width:200px" %)String

322

|(% style="width:200px" %)EventParameter.NUM_ADULTS|(% style="width:200px" %)Integer

323

|(% style="width:200px" %)EventParameter.NUM_CHILDREN|(% style="width:200px" %)Integer

324

|(% style="width:200px" %)EventParameter.NUM_INFANTS|(% style="width:200px" %)Integer

325

|(% style="width:200px" %)EventParameter.SUGGESTED_HOTELS|(% style="width:200px" %)String[]

326

|(% style="width:200px" %)EventParameter.USER_SCORE|(% style="width:200px" %)Float

327

|(% style="width:200px" %)EventParameter.HOTEL_SCORE|(% style="width:200px" %)Float

328

|(% style="width:200px" %)EventParameter.PURCHASE_CURRENCY|(% style="width:200px" %)String

329

|(% style="width:200px" %)EventParameter.PREFERRED_STAR_RATINGS|(% style="width:200px" %)Integer[2]

330

|(% style="width:200px" %)EventParameter.PREFERRED_PRICE_RANGE|(% style="width:200px" %)Integer[2]

331

|(% style="width:200px" %)EventParameter.PREFERRED_NEIGHBORHOODS|(% style="width:200px" %)String[]

332

|(% style="width:200px" %)EventParameter.PREFERRED_NUM_STOPS|(% style="width:200px" %)Integer

333

|(% style="width:200px" %)EventParameter.CONTENT|(% style="width:200px" %)String

334

|(% style="width:200px" %)EventParameter.PARAM_1|(% style="width:200px" %)String

335

|(% style="width:200px" %)EventParameter.PARAM_2|(% style="width:200px" %)String

336

|(% style="width:200px" %)EventParameter.PARAM_3|(% style="width:200px" %)String

337

|(% style="width:200px" %)EventParameter.PARAM_4|(% style="width:200px" %)String

338

|(% style="width:200px" %)EventParameter.PARAM_5|(% style="width:200px" %)String

339

|(% style="width:200px" %)EventParameter.PARAM_6|(% style="width:200px" %)String

340

|(% style="width:200px" %)EventParameter.PARAM_7|(% style="width:200px" %)String

341

|(% style="width:200px" %)EventParameter.PARAM_8|(% style="width:200px" %)String

342

|(% style="width:200px" %)EventParameter.PARAM_9|(% style="width:200px" %)String

343

|(% style="width:200px" %)EventParameter.PARAM_10|(% style="width:200px" %)String

344

345

= 5. Additional Configuration (Optional) =

346

347

== 5.1 Setting Permissions ==

348

349

SDK will collect data types to which it has permission.

350

351

IMPORTANT: On Android >= 6.0 your application must also request for some permissions at runtime.

352

MobigateSDK doesn’t request for any permissions on its own.([[Learnmore>>https://developer.android.com/training/permissions/requesting.html]])

353

354

== 5.2 Configuring data Collectors ==

355

356

By default, when calling startService() MobigateSDK will collect all kinds of data supported by the SDK and allowed by the permissions from Android manifest (and runtime permissions on Android >=6.0). To ensure that you collect as much data as possible add the following permissions into your application:

357

358

359

<uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION" ></uses-permission>

360

<uses-permission android:name="android.permission.ACCESS_FINE_LOCATION" ></uses-permission>

361

<uses-permission android:name="android.permission.CHANGE_WIFI_STATE" ></uses-permission>

362

<uses-permission android:name="android.permission.ACCESS_NETWORK_STATE" ></uses-permission>

363

<uses-permission android:name="android.permission.ACCESS_WIFI_STATE" ></uses-permission>

364

<uses-permission android:name="android.permission.READ_PHONE_STATE" ></uses-permission>

365

<uses-permission android:name="android.permission.GET_PACKAGE_SIZE" ></uses-permission>

366

<uses-permission android:name="com.android.browser.permission.READ_HISTORY_BOOKMARKS" ></uses-permission>

367

<uses-permission android:name="android.permission.GET_TASKS" ></uses-permission>

368

<uses-permission android:name="android.permission.READ_CALENDAR" ></uses-permission>

369

<uses-permission android:name="android.permission.READ_CONTACTS" ></uses-permission>

370

<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" ></uses-permission>

371

<uses-permission android:name="android.permission.READ_USER_DICTIONARY" ></uses-permission>

372

<uses-permission android:name="android.permission.BLUETOOTH" ></uses-permission>

373

<uses-permission android:name="android.permission.NFC" ></uses-permission>

374

<uses-permission android:name="android.permission.PACKAGE_USAGE_STATS" ></uses-permission>

375

<uses-permission android:name="com.google.android.gms.permission.ACTIVITY_RECOGNITION" ></uses-permission>

376

377

378

* You may specify subset of data types to be collected:

379

380

381

sdk.enableDataCollector(true, new int[] { DataCollector.GEOLOCATION,DataCollector.MEDIA_FILES, DataCollector.BROWSER, … });

382

sdk.startService(context);

383

384

385

* Or add them one by one:

386

387

388

sdk.enableDataCollector(true, DataCollector.BROWSER);

389

sdk.enableDataCollector(true, DataCollector.GEOLOCATION);

390

......

391

sdk.startService(context);

* Collectors list:

package pl.spicymobile.mobience.sdk;

/***

* Data collectors

*/

public class DataCollector {

403

/**

404

* Collect all application's info on device

405

* Optional permission:

406

* android.permission.GET_PACKAGE_SIZE

407

*/

408

public final static int APPS_LIST = 0;

409

410

/**

411

* Class collect time active an application

412

* Required permissions:

413

* android.permission.PACKAGE_USAGE_STATS (obligatory on android sdk >= Lollipop 5.0)

414

* android.permission.GET_TASKS (obligatory on android sdk <= Kitkat 4.4)

415

*/

416

public final static int APPS_USAGE = 1;

417

418

/**

419

* BatteryInfoCollector collects battery info: level; and charge event

420

*/

421

public final static int BATTERY = 2;

422

423

/**

424

* Collecting data on browser history, bookmarks, pharses

425

* Required permissions:

426

* com.android.browser.permission.READ_HISTORY_BOOKMARKS (Removed since android sdk >= Marshmallow 6.0) on Android api level < Lollipop 5.0

427

* turned on accessibility for application on Android api level >= Lollipop 5.0

428

*/

429

public final static int BROWSER = 3;

430

431

/**

432

* Collects calendar events data of a device, with a range of days : before 100 days and after 100 days with the collecting day

433

* Required permissions:

434

* android.permission.READ_CALENDAR

435

*/

436

public final static int CALENDAR_EVENTS = 4;

437

438

/**

439

* Collect process running cpu on device at time request

440

*/

441

public final static int CPU_PROCESS = 6;

442

443

/**

444

* Collect all data Dictionary of user on device

445

* Required permissions:

446

* android.permission.READ_USER_DICTIONARY

447

*/

448

public final static int DICTIONARY = 7;

449

450

/**

451

* Geolocalization coordinates of a device, information of current GSM cell and GSM signal strength

452

* Required permissions:

453

* android.permission.ACCESS_FINE_LOCATION or android.permission.ACCESS_COARSE_LOCATION

454

*/

455

public final static int GEOLOCATION = 8;

456

457

/**

458

* Collect all data about headset plugin's information

459

*/

460

public final static int HEADSET_PLUG = 9;

461

462

/**

463

* Gather Media files information of device

464

* Required permissions:

465

* android.permission.WRITE_EXTERNAL_STORAGE3

466

* android.permission.READ_EXTERNAL_STORAGE3 (on Android api level >= Jelly Bean 4.1)

467

*/

468

public final static int MEDIA_FILES = 10;

469

470

/**

471

* Collect used memory info

472

*/

473

public final static int MEMORY_USEAGE = 11;

474

475

/**

476

* Collect about connection information: "wifi" or "mobile data" or "no connection"

477

* Required permissions:

478

* android.permission.ACCESS_NETWORK_STATE

479

*/

480

public final static int NETWORK_CONNECTION = 13;

481

482

/**

483

* Collect all network usage data from all application on device

484

*/

485

public final static int NETWORK_USEAGE = 14;

486

487

/**

488

* Collect all package change event (install new app, remove app, data clear, restart app)

489

*/

490

public final static int PACKAGE_CHANGE = 15;

491

492

/**

493

* Collect informations of a device, such as: Identifiers of device model, system version, IMSI, IP, network operator of SIM card and mobile network, WiFi network data, etc.

494

* Optional permission:

495

* android.permission.READ_PHONE_STATE

496

* android.permission.ACCESS_NETWORK_STATE

497

* android.permission.ACCESS_WIFI_STATE

498

*/

499

public final static int PHONE_INFO = 16;

500

501

/**

502

* Catch event roaming

503

* Required permissions:

504

* android.permission.ACCESS_NETWORK_STATE

505

*/

506

public final static int ROAMING = 17;

507

508

/**

509

* Collect data about device's orientation

510

*/

511

public final static int SCREEN_ORIENTED = 18;

512

513

/**

514

* Collect phone signal info

515

*/

516

public final static int SIGNAL_STRENGTH = 19;

517

518

/**

519

* Collect time change profile mode

520

*/

521

public final static int PROFILE_MODE = 20;

522

523

/**

524

* Gather list of visible WiFi networks, information of each wifi

525

* Required permission:

526

* android.permission.ACCESS_WIFI_STATE

527

* Android <= 8.1 (sdk level <= 27):

528

* android.permission.ACCESS_FINE_LOCATION or android.permission.ACCESS_COARSE_LOCATION

529

* android.permission.CHANGE_WIFI_STATE

530

* Android 9.0, 10 (sdk level 28, 29)

531

* enabled location services

532

* Applications targeting Android 10 (API level 29) SDK or higher, has the android.permission.ACCESS_FINE_LOCATION

533

*/

534

public final static int WIFI_DATA_CONNECTION = 21;

/**

* SDKApp

* ion gathers every week list of all the Android permissions that it have and list of enabled data collectors from MobienceSDK

539

*/

540

public final static int PERMISSION_COLLECTOR = 22;

541

542

/**

543

* NFC collector collects information of NFC funtion of that device, contains normal NFC NFED information

544

* Required permissions:

545

* android.permission.NFC

546

*/

547

public final static int NFC_COLLECTOR = 23;

548

549

/**

550

* Bluetooth collector collects information of Bluetooth funtion of that device, contains normal Bluetooth information

551

* Required permissions:

552

* android.permission.BLUETOOTH

553

*/

554

public final static int BLUETOOTH_COLLECTOR = 24;

555

556

/**

557

* Bluetooth device collector collects information of detecting connected devices via bluetooth

558

* Required permissions:

559

* android.permission.BLUETOOTH

560

*/

561

public final static int BLUETOOTH_DEVICES_COLLECTOR = 26;

562

563

/**

564

* Activity recognition collector collects information about detected user activities (walking, running, driving, etc.)

565

* Required permission:

566

* com.google.android.gms.permission.ACTIVITY_RECOGNITION

567

*/

568

public final static int MOVEMENT_COLLECTOR = 27;

569

570

/**

571

* Facebook collector collect informationabout user

572

*/

573

public final static int FACEBOOK_NETWORK_COLLECTOR = 28;

574

575

/**

576

* Root data collector collects information if device is rooted

577

*/

578

public final static int ROOT_COLLECTOR = 29;

579

580

/**

581

* Total collectors size

582

*/

583

public final static int TOTAL_SIZE = 27;

}

== 5.3 Set email ==

* To set user’s email, call:

592

593

594

MobigateSDK.get().setEmail("your_email");

595

596

597

* Or with builder method:

598

599

600

SDK sdk = new MobigateSDK.Builder(getApplicationContext(),"Api_key").setEmail("your_email").build();

601

602

603

== 5.4 Custom user ID ==

604

605

You may use your custom userID for marking data. By default we are using device ID and emails for matching. Set it before starting the service using MobigateSDk.Builder method.

606

607

608

MobigateSDK.Builder(getApplicationContext(),"Api_key").setCustomUserID("customID").build();

609

610

611

== 5.5 User and device identification ==

612

613

MobigateSDK is gathering following user/device identifiers:

614

615

* ANDROID_ID,

616

* Android AdvertisingID (AAID) - requires Google Play Services implemented in app and available on device,

617

* Mobigate own device ID (random UUID stored permanently on the device),

618

* custom user ID, if set by method setCustomUserID(),

619

* e-mail - provided by setEmail() method or read automatically if GET_ACCOUNTS permission is granted. This is usually user’s e-mail from Google Play account,

620

* Wi-Fi MAC address - when Wi-Fi is enabled and ACCESS_WIFI_STATE permission is granted,

621

* device’s „serial” number, as provided by Android,

622

* IMEI - if device has telephony module. Requires READ_PHONE_STATE permission.

623

624

By default MobigateSDK is gathering all identifiers, which it can read. You can indicate which fields gather to comply with your privacy policy. To specify gathering of given identifier, call Builder:

625

626

627

MobigateSDK.Builder().enableUserField(SDK.UserField... fields)

628

629

630

Identifiers that can be disabled are: EMAIL, MAC, SERIAL, IMEI, IMSI.

631

632

== 5.6 Logging and debugging ==

633

634

Logging is enabled only while application is in DEBUG mode and is on by default.

635

636

== 5.7 SDK information ==

637

638

To get SDK info (version):

639

640

641

MobigateSDK.get().getSDKInfo();

642

643

644

== 5.8 Data gather policy ==

645

646

By default, on Android phones with sdk level lower than 26 MobigateSDK does not display a persistent notification when the service starts, but gathers data in the background

647

On Android phones with sdk level >= 26 Google Play rules prohibit collecting data in background, without notification for user ([[Learn more>>https://play.google.com/intl/en-US_ALL/about/privacy-security/malicious-behavior/]]). In that case MobigateSDK by default block data gathering in background. You can change the default behavior by use the Builder following method:

648

649

650

MobigateSDK.Builder().setDataGatherPolicy(SDK.MONITOR_STATE.DEFAULT,"optional_notification_text")

651

652

653

Possible monitor states:

654

655

* SDK.MONITOR_STATE.DEFAULT,

656

* SDK.MONITOR_STATE.HIDE_TRAY,

657

* SDK.MONITOR_STATE.BLOCK_DATA_BG.

658

659

== 5.9 Advertising systems ==

660

661

* Method that returns the IDs user profiles

662

663

Software MobigateSDK based on data collected assigns user IDs profile. IDs can be use to send to an ad server.

664

To enable functionality (only once, necessarily before the first call Mobigate.startService()):

665

666

667

MobigateSDK.get().enableIDsProfiles(true);

668

669

670

To get the IDs profiles for the user (at any time and anywhere in the application):

671

672

673

MobigateSDK.get().getIDsProfiles();

674

675

676

List of IDs profiles in the application memory is updated (synchronized with the server) at specified intervals.

677

678

* Optional integration with AdOcean module from GemiusSDK

679

680

681

Map<String, Long> MobigateSDK.get().getAdOceanTargeting();

682

683

684

This method is intended for use with "setNumericalVariables" method from GemiusSDK (AdOcean module).

Sample usage:

FullScreenAd interstitial1 = new FullScreenAd(context, INTERSTITIAL1_PLACEMENT_ID);

689

interstitial1.setNumericalVariables(MobigateSDK.getAdOceanTargeting());

690

interstitial1.open();

691

692

693

Same applies to billboard adds.

694

695

This way user identifiers are passed to AdOcean AdServer as „numerical variables”, that can be used for ads targeting.

696

697

**getAdOceanTargeting()** method returns 3 different identifiers of a user, encoded into a map of AdOcean numerical variables.

698

699

* Mobigate user identifier,

700

* ANDROID_ID,

701

* Android Advertising ID (requires Google Play Services implemented in app and available on device).

702

703

Please ask our representative for instructions on configuring targeting in AdOcean panel.

704

705

706

= 6. Testing SDK integration =

707

708

Integrating our SDK is easy and straightforward. Nevertheless, we highly recommend that you test the integration before submitting the app to the app store.

709

\\The easiest way to test integration is to install our testing application from the play store. [[You can find it here>>https://play.google.com/store/apps/details?id=pl.spicymobile.sdk.integration]]

710

711

712

Testing application is very simple. After installation, point your application from list and run the test. The result will appear in a new application window. If no warning signs have appeared, it means that the library is well integrated into your application.

Wiki source code of Android SDK integration