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 (latest version is 1.0.19, you can fin the repository [[here>>https://repository.spicymobile.pl/#browse/pl.spicymobile.mobigate.sdk]]):

dependencies {

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

...

}

== WorkManager known issues ==

43

44

In order to minimise any possibility of impacting behavior of your application Mobigate SDK does the majority of its work in a second process. There are some known issuse (described [[here>>https://issuetracker.google.com/issues/160625831]]) regarding performance of WorkManager in context of multiprocess applications. In ofred to avoid those issues please use androidx.work:work-multiprocess:2.5.0 or higher as your WorkManager gradle dependency.

45

46

= 3. SDK Initialization =

47

48

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

49

50

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

51

52

53

public class MyApplication extends Application {

54

@Override

55

public void onCreate() {

56

super.onCreate();

57

/*minimum library configuration*/

58

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

59

/*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.

74

75

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

76

77

(% class="table-bordered" %)

78

|(% 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**

79

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

80

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

81

There can be more than one

82

83

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"]]).

84

85

== 4.2 Implementation ==

86

87

Tracking in-app events is performed by two methods:

88

89

90

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

91

.setParameter(EventParameter.CITY,"warszawa")

92

.setParameter(EventParameter.CURRENCY, "PLN")

93

.setParameter("UserChoiceParameterName", 12345)

94

.build())

95

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

96

97

98

== 4.3 Event categories ==

99

100

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

101

102

{{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"}}

103

104

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

105

**Event category:** EventCategory.LEVEL_ACCOMPLISHED

106

**Recommended parameters:** LEVEL, SCORE

107

108

109

{{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"}}

110

111

\\**Description:** Track payment info

112

**Event category:** EventCategory.ADD_PAYMENT_INFO

113

**Recommended parameters:** SUCCESS

114

115

116

{{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"}}

117

118

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

119

**Event category:** EventCategory.ADD_TO_BASKET

120

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

121

122

123

{{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"}}

124

125

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

126

**Event category:** EventCategory.REMOVED_FROM_BASKET

127

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

128

129

130

{{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"}}

131

132

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

133

**Event category:** EventCategory.ADD_TO_WISH_LIST

134

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

135

136

137

{{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"}}

138

139

\\**Description:** Track registration

140

**Event category:** EventCategory.REGISTRATION

141

**Recommended parameters:** REGISTRATION_METHOD

142

143

144

{{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"}}

145

146

\\**Description:** Track tutorial completion

147

**Event category:** EventCategory.TUTORIAL_COMPLETION

148

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

149

150

151

{{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"}}

152

153

\\**Description:** Track triggered checkout

154

**Event category:** EventCategory.TRIGGER_CHECKOUT

155

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

156

157

158

{{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"}}

159

160

\\**Description:** Track purchased item

161

**Event category:** EventCategory.PURCHASE

162

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

163

164

165

{{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"}}

166

167

\\**Description:** Track subscription purchase

168

**Event category:** EventCategory.SUBSCRIBE

169

**Recommended parameters:** REVENUE, CURRENCY

170

171

172

{{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"}}

173

174

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

175

**Event category:** EventCategory.BEGIN_TRIAL

176

**Recommended parameters:** PRICE, CURRENCY

177

178

179

{{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"}}

180

181

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

182

**Event category:** EventCategory.RATE

183

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

184

185

186

{{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"}}

187

\\**Description:** Track search event

188

**Event category:** EventCategory.SEARCH

189

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

190

191

192

{{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"}}

193

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

194

**Event category:** EventCategory.USED_CREDIT

195

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

196

197

198

{{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"}}

199

\\**Description:** Track achievement unlock

200

**Event category:** EventCategory.UNLOCKED_ACHIEVEMENT

201

**Recommended parameters:** DESCRIPTION

202

203

204

{{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"}}

205

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

206

**Event category:** EventCategory.VIEW_CONTENT

207

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

208

209

210

{{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"}}

211

\\**Description:** Track list event

212

**Event category:** EventCategory.VIEW_LIST

213

**Recommended parameters:** CONTENT_TYPE, CONTENT_LIST

214

215

216

{{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"}}

217

\\**Description:** Track ad click

218

**Event category:** EventCategory.CLICK_AD

219

**Recommended parameters:** CONTENT_TYPE, CONTENT_ID

220

221

222

{{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"}}

223

\\**Description:** Track view ad

224

**Event category:** EventCategory.VIEW_AD

225

**Recommended parameters:** CONTENT_TYPE, CONTENT_ID

226

227

228

{{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"}}

229

\\**Description:** Track booking event

230

**Event category:** EventCategory.EVENT_BOOKING

231

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

232

233

234

{{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"}}

235

\\**Description:** Track share event

236

**Event category:** EventCategory.SHARE

237

**Recommended parameters:** DESCRIPTION

238

239

240

{{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"}}

241

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

242

**Event category:** EventCategory.INVITE

243

**Recommended parameters:** NONE

244

245

246

{{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"}}

247

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

248

**Event category:** EventCategory.LOGIN

249

**Recommended parameters:** NONE

250

251

252

{{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"}}

253

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

254

**Event category:** EventCategory.EVENT_RETURN

255

**Recommended parameters:** NONE

256

257

258

{{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"}}

259

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

260

**Event category:** EventCategory.OPENED_PUSH_NOTIFICATION

261

**Recommended parameters:** NONE

262

263

264

{{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"}}

265

\\**Description:** Track update event

266

**Event category:** EventCategory.UPDATE

267

**Recommended parameters:** CONTENT_ID

== 4.4 Event parameters ==

272

273

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.

274

275

(% class="table-bordered" %)

276

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

277

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

278

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

279

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

280

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

281

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

282

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

283

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

284

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

285

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

286

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

287

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

288

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

289

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

290

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

291

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

292

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

293

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

294

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

295

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

296

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

297

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

298

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

299

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

300

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

301

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

302

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

303

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

304

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

305

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

306

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

307

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

308

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

309

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

310

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

311

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

312

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

313

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

314

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

315

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

316

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

317

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

318

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

319

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

320

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

321

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

322

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

323

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

324

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

325

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

326

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

327

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

328

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

329

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

330

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

331

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

332

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

333

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

334

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

335

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

336

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

337

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

338

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

339

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

340

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

341

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

342

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

343

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

344

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

345

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

346

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

347

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

348

349

= 5. Additional Configuration (Optional) =

350

351

== 5.1 Setting Permissions ==

352

353

SDK will collect data types to which it has permission.

354

355

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

356

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

357

358

== 5.2 Configuring data Collectors ==

359

360

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:

361

362

363

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

364

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

365

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

366

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

367

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

368

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

369

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

370

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

371

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

372

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

373

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

374

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

375

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

376

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

377

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

378

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

379

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

380

381

382

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

383

384

385

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

386

sdk.startService(context);

387

388

389

* Or add them one by one:

390

391

392

sdk.enableDataCollector(true, DataCollector.BROWSER);

393

sdk.enableDataCollector(true, DataCollector.GEOLOCATION);

394

......

395

sdk.startService(context);

* Collectors list:

package pl.spicymobile.mobience.sdk;

/***

* Data collectors

*/

public class DataCollector {

407

/**

408

* Collect all application's info on device

409

* Optional permission:

410

* android.permission.GET_PACKAGE_SIZE

411

*/

412

public final static int APPS_LIST = 0;

413

414

/**

415

* Class collect time active an application

416

* Required permissions:

417

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

418

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

419

*/

420

public final static int APPS_USAGE = 1;

421

422

/**

423

* BatteryInfoCollector collects battery info: level; and charge event

424

*/

425

public final static int BATTERY = 2;

426

427

/**

428

* Collecting data on browser history, bookmarks, pharses

429

* Required permissions:

430

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

431

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

432

*/

433

public final static int BROWSER = 3;

434

435

/**

436

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

437

* Required permissions:

438

* android.permission.READ_CALENDAR

439

*/

440

public final static int CALENDAR_EVENTS = 4;

441

442

/**

443

* Collect process running cpu on device at time request

444

*/

445

public final static int CPU_PROCESS = 6;

446

447

/**

448

* Collect all data Dictionary of user on device

449

* Required permissions:

450

* android.permission.READ_USER_DICTIONARY

451

*/

452

public final static int DICTIONARY = 7;

453

454

/**

455

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

456

* Required permissions:

457

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

458

*/

459

public final static int GEOLOCATION = 8;

460

461

/**

462

* Collect all data about headset plugin's information

463

*/

464

public final static int HEADSET_PLUG = 9;

465

466

/**

467

* Gather Media files information of device

468

* Required permissions:

469

* android.permission.WRITE_EXTERNAL_STORAGE3

470

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

471

*/

472

public final static int MEDIA_FILES = 10;

473

474

/**

475

* Collect used memory info

476

*/

477

public final static int MEMORY_USEAGE = 11;

478

479

/**

480

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

481

* Required permissions:

482

* android.permission.ACCESS_NETWORK_STATE

483

*/

484

public final static int NETWORK_CONNECTION = 13;

485

486

/**

487

* Collect all network usage data from all application on device

488

*/

489

public final static int NETWORK_USEAGE = 14;

490

491

/**

492

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

493

*/

494

public final static int PACKAGE_CHANGE = 15;

495

496

/**

497

* 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.

498

* Optional permission:

499

* android.permission.READ_PHONE_STATE

500

* android.permission.ACCESS_NETWORK_STATE

501

* android.permission.ACCESS_WIFI_STATE

502

*/

503

public final static int PHONE_INFO = 16;

504

505

/**

506

* Catch event roaming

507

* Required permissions:

508

* android.permission.ACCESS_NETWORK_STATE

509

*/

510

public final static int ROAMING = 17;

511

512

/**

513

* Collect data about device's orientation

514

*/

515

public final static int SCREEN_ORIENTED = 18;

516

517

/**

518

* Collect phone signal info

519

*/

520

public final static int SIGNAL_STRENGTH = 19;

521

522

/**

523

* Collect time change profile mode

524

*/

525

public final static int PROFILE_MODE = 20;

526

527

/**

528

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

529

* Required permission:

530

* android.permission.ACCESS_WIFI_STATE

531

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

532

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

533

* android.permission.CHANGE_WIFI_STATE

534

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

535

* enabled location services

536

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

537

*/

538

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

543

*/

544

public final static int PERMISSION_COLLECTOR = 22;

545

546

/**

547

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

548

* Required permissions:

549

* android.permission.NFC

550

*/

551

public final static int NFC_COLLECTOR = 23;

552

553

/**

554

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

555

* Required permissions:

556

* android.permission.BLUETOOTH

557

*/

558

public final static int BLUETOOTH_COLLECTOR = 24;

559

560

/**

561

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

562

* Required permissions:

563

* android.permission.BLUETOOTH

564

*/

565

public final static int BLUETOOTH_DEVICES_COLLECTOR = 26;

566

567

/**

568

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

569

* Required permission:

570

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

571

*/

572

public final static int MOVEMENT_COLLECTOR = 27;

573

574

/**

575

* Facebook collector collect informationabout user

576

*/

577

public final static int FACEBOOK_NETWORK_COLLECTOR = 28;

578

579

/**

580

* Root data collector collects information if device is rooted

581

*/

582

public final static int ROOT_COLLECTOR = 29;

583

584

/**

585

* Total collectors size

586

*/

587

public final static int TOTAL_SIZE = 27;

}

== 5.3 Set email ==

* To set user’s email, call:

596

597

598

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

599

600

601

* Or with builder method:

602

603

604

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

605

606

607

== 5.4 Custom user ID ==

608

609

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.

610

611

612

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

613

614

615

== 5.5 User and device identification ==

616

617

MobigateSDK is gathering following user/device identifiers:

618

619

* ANDROID_ID,

620

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

621

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

622

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

623

* 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,

624

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

625

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

626

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

627

628

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:

629

630

631

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

632

633

634

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

635

636

== 5.6 Logging and debugging ==

637

638

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

639

640

== 5.7 SDK information ==

641

642

To get SDK info (version):

643

644

645

MobigateSDK.get().getSDKInfo();

646

647

648

== 5.8 Data gather policy ==

649

650

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

651

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:

652

653

654

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

655

656

657

Possible monitor states:

658

659

* SDK.MONITOR_STATE.DEFAULT,

660

* SDK.MONITOR_STATE.HIDE_TRAY,

661

* SDK.MONITOR_STATE.BLOCK_DATA_BG.

662

663

== 5.9 Advertising systems ==

664

665

* Method that returns the IDs user profiles

666

667

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

668

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

669

670

671

MobigateSDK.get().enableIDsProfiles(true);

672

673

674

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

675

676

677

MobigateSDK.get().getIDsProfiles();

678

679

680

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

681

682

* Optional integration with AdOcean module from GemiusSDK

683

684

685

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

686

687

688

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

Sample usage:

FullScreenAd interstitial1 = new FullScreenAd(context, INTERSTITIAL1_PLACEMENT_ID);

693

interstitial1.setNumericalVariables(MobigateSDK.getAdOceanTargeting());

694

interstitial1.open();

695

696

697

Same applies to billboard adds.

698

699

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

700

701

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

702

703

* Mobigate user identifier,

704

* ANDROID_ID,

705

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

706

707

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

708

709

710

= 6. Testing SDK integration =

711

712

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

713

\\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]]

714

715

716

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

MobigateSDK Center