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.

66

67

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

68

69

(% class="table-bordered" %)

70

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

71

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

72

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

73

There can be more than one

74

75

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

76

77

== 4.2 Implementation ==

78

79

Tracking in-app events is performed by two methods:

80

81

82

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

83

.setParameter(EventParameter.CITY,"warszawa")

84

.setParameter(EventParameter.CURRENCY, "PLN")

85

.setParameter("UserChoiceParameterName", 12345)

86

.build())

87

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

88

89

90

== 4.3 Event categories ==

91

92

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

93

94

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

95

96

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

97

**Event category:** EventCategory.LEVEL_ACCOMPLISHED

98

**Recommended parameters:** LEVEL, SCORE

99

100

101

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

102

103

\\**Description:** Track payment info

104

**Event category:** EventCategory.ADD_PAYMENT_INFO

105

**Recommended parameters:** SUCCESS

106

107

108

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

109

110

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

111

**Event category:** EventCategory.ADD_TO_BASKET

112

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

113

114

115

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

116

117

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

118

**Event category:** EventCategory.REMOVED_FROM_BASKET

119

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

120

121

122

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

123

124

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

125

**Event category:** EventCategory.ADD_TO_WISH_LIST

126

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

127

128

129

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

130

131

\\**Description:** Track registration

132

**Event category:** EventCategory.REGISTRATION

133

**Recommended parameters:** REGISTRATION_METHOD

134

135

136

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

137

138

\\**Description:** Track tutorial completion

139

**Event category:** EventCategory.TUTORIAL_COMPLETION

140

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

141

142

143

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

144

145

\\**Description:** Track triggered checkout

146

**Event category:** EventCategory.TRIGGER_CHECKOUT

147

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

148

149

150

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

151

152

\\**Description:** Track purchased item

153

**Event category:** EventCategory.PURCHASE

154

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

155

156

157

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

158

159

\\**Description:** Track subscription purchase

160

**Event category:** EventCategory.SUBSCRIBE

161

**Recommended parameters:** REVENUE, CURRENCY

162

163

164

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

165

166

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

167

**Event category:** EventCategory.BEGIN_TRIAL

168

**Recommended parameters:** PRICE, CURRENCY

169

170

171

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

172

173

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

174

**Event category:** EventCategory.RATE

175

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

176

177

178

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

179

\\**Description:** Track search event

180

**Event category:** EventCategory.SEARCH

181

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

182

183

184

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

185

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

186

**Event category:** EventCategory.USED_CREDIT

187

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

188

189

190

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

191

\\**Description:** Track achievement unlock

192

**Event category:** EventCategory.UNLOCKED_ACHIEVEMENT

193

**Recommended parameters:** DESCRIPTION

194

195

196

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

197

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

198

**Event category:** EventCategory.VIEW_CONTENT

199

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

200

201

202

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

203

\\**Description:** Track list event

204

**Event category:** EventCategory.VIEW_LIST

205

**Recommended parameters:** CONTENT_TYPE, CONTENT_LIST

206

207

208

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

209

\\**Description:** Track ad click

210

**Event category:** EventCategory.CLICK_AD

211

**Recommended parameters:** CONTENT_TYPE, CONTENT_ID

212

213

214

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

215

\\**Description:** Track view ad

216

**Event category:** EventCategory.VIEW_AD

217

**Recommended parameters:** CONTENT_TYPE, CONTENT_ID

218

219

220

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

221

\\**Description:** Track booking event

222

**Event category:** EventCategory.EVENT_BOOKING

223

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

224

225

226

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

227

\\**Description:** Track share event

228

**Event category:** EventCategory.SHARE

229

**Recommended parameters:** DESCRIPTION

230

231

232

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

233

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

234

**Event category:** EventCategory.INVITE

235

**Recommended parameters:** NONE

236

237

238

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

239

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

240

**Event category:** EventCategory.LOGIN

241

**Recommended parameters:** NONE

242

243

244

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

245

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

246

**Event category:** EventCategory.EVENT_RETURN

247

**Recommended parameters:** NONE

248

249

250

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

251

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

252

**Event category:** EventCategory.OPENED_PUSH_NOTIFICATION

253

**Recommended parameters:** NONE

254

255

256

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

257

\\**Description:** Track update event

258

**Event category:** EventCategory.UPDATE

259

**Recommended parameters:** CONTENT_ID

== 4.4 Event parameters ==

264

265

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.

266

267

(% class="table-bordered" %)

268

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

269

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

270

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

271

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

272

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

273

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

274

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

275

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

276

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

277

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

278

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

279

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

280

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

281

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

282

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

283

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

284

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

285

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

286

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

287

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

288

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

289

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

290

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

291

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

292

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

293

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

294

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

295

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

296

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

297

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

298

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

299

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

300

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

301

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

302

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

303

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

304

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

305

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

306

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

307

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

308

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

309

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

310

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

311

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

312

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

313

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

314

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

315

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

316

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

317

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

318

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

319

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

320

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

321

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

322

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

323

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

324

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

325

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

326

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

327

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

328

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

329

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

330

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

331

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

332

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

333

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

334

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

335

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

336

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

337

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

338

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

339

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

340

341

= 5. Additional Configuration (Optional) =

342

343

== 5.1 Setting Permissions ==

344

345

SDK will collect data types to which it has permission.

346

347

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

348

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

349

350

== 5.2 Configuring data Collectors ==

351

352

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:

353

354

355

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

356

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

357

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

358

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

359

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

360

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

361

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

362

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

363

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

364

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

365

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

366

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

367

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

368

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

369

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

370

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

371

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

372

373

374

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

375

376

377

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

sdk.startService();

* Or add them one by one:

382

383

384

sdk.enableDataCollector(true, DataCollector.BROWSER);

385

sdk.enableDataCollector(true, DataCollector.GEOLOCATION);

......

sdk.startService();

* Collectors list:

package pl.spicymobile.mobience.sdk;

/***

* Data collectors

*/

public class DataCollector {

399

/**

400

* Collect all application's info on device

401

* Optional permission:

402

* android.permission.GET_PACKAGE_SIZE

403

*/

404

public final static int APPS_LIST = 0;

405

406

/**

407

* Class collect time active an application

408

* Required permissions:

409

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

410

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

411

*/

412

public final static int APPS_USAGE = 1;

413

414

/**

415

* BatteryInfoCollector collects battery info: level; and charge event

416

*/

417

public final static int BATTERY = 2;

418

419

/**

420

* Collecting data on browser history, bookmarks, pharses

421

* Required permissions:

422

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

423

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

424

*/

425

public final static int BROWSER = 3;

426

427

/**

428

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

429

* Required permissions:

430

* android.permission.READ_CALENDAR

431

*/

432

public final static int CALENDAR_EVENTS = 4;

433

434

/**

435

* Collect process running cpu on device at time request

436

*/

437

public final static int CPU_PROCESS = 6;

438

439

/**

440

* Collect all data Dictionary of user on device

441

* Required permissions:

442

* android.permission.READ_USER_DICTIONARY

443

*/

444

public final static int DICTIONARY = 7;

445

446

/**

447

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

448

* Required permissions:

449

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

450

*/

451

public final static int GEOLOCATION = 8;

452

453

/**

454

* Collect all data about headset plugin's information

455

*/

456

public final static int HEADSET_PLUG = 9;

457

458

/**

459

* Gather Media files information of device

460

* Required permissions:

461

* android.permission.WRITE_EXTERNAL_STORAGE3

462

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

463

*/

464

public final static int MEDIA_FILES = 10;

465

466

/**

467

* Collect used memory info

468

*/

469

public final static int MEMORY_USEAGE = 11;

470

471

/**

472

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

473

* Required permissions:

474

* android.permission.ACCESS_NETWORK_STATE

475

*/

476

public final static int NETWORK_CONNECTION = 13;

477

478

/**

479

* Collect all network usage data from all application on device

480

*/

481

public final static int NETWORK_USEAGE = 14;

482

483

/**

484

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

485

*/

486

public final static int PACKAGE_CHANGE = 15;

487

488

/**

489

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

490

* Optional permission:

491

* android.permission.READ_PHONE_STATE

492

* android.permission.ACCESS_NETWORK_STATE

493

* android.permission.ACCESS_WIFI_STATE

494

*/

495

public final static int PHONE_INFO = 16;

496

497

/**

498

* Catch event roaming

499

* Required permissions:

500

* android.permission.ACCESS_NETWORK_STATE

501

*/

502

public final static int ROAMING = 17;

503

504

/**

505

* Collect data about device's orientation

506

*/

507

public final static int SCREEN_ORIENTED = 18;

508

509

/**

510

* Collect phone signal info

511

*/

512

public final static int SIGNAL_STRENGTH = 19;

513

514

/**

515

* Collect time change profile mode

516

*/

517

public final static int PROFILE_MODE = 20;

518

519

/**

520

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

521

* Required permission:

522

* android.permission.ACCESS_WIFI_STATE

523

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

524

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

525

* android.permission.CHANGE_WIFI_STATE

526

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

527

* enabled location services

528

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

529

*/

530

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

535

*/

536

public final static int PERMISSION_COLLECTOR = 22;

537

538

/**

539

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

540

* Required permissions:

541

* android.permission.NFC

542

*/

543

public final static int NFC_COLLECTOR = 23;

544

545

/**

546

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

547

* Required permissions:

548

* android.permission.BLUETOOTH

549

*/

550

public final static int BLUETOOTH_COLLECTOR = 24;

551

552

/**

553

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

554

* Required permissions:

555

* android.permission.BLUETOOTH

556

*/

557

public final static int BLUETOOTH_DEVICES_COLLECTOR = 26;

558

559

/**

560

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

561

* Required permission:

562

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

563

*/

564

public final static int MOVEMENT_COLLECTOR = 27;

565

566

/**

567

* Facebook collector collect informationabout user

568

*/

569

public final static int FACEBOOK_NETWORK_COLLECTOR = 28;

570

571

/**

572

* Root data collector collects information if device is rooted

573

*/

574

public final static int ROOT_COLLECTOR = 29;

575

576

/**

577

* Total collectors size

578

*/

579

public final static int TOTAL_SIZE = 27;

}

== 5.3 Set email ==

* To set user’s email, call:

588

589

590

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

591

592

593

* Or with builder method:

594

595

596

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

597

598

599

== 5.4 Custom user ID ==

600

601

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.

602

603

604

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

605

606

607

== 5.5 User and device identification ==

608

609

MobigateSDK is gathering following user/device identifiers:

610

611

* ANDROID_ID,

612

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

613

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

614

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

615

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

616

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

617

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

618

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

619

620

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:

621

622

623

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

624

625

626

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

627

628

== 5.6 Logging and debugging ==

629

630

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

631

632

== 5.7 SDK information ==

633

634

To get SDK info (version):

635

636

637

MobigateSDK.get().getSDKInfo();

638

639

640

== 5.8 Data gather policy ==

641

642

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

643

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:

644

645

646

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

647

648

649

Possible monitor states:

650

651

* SDK.MONITOR_STATE.DEFAULT,

652

* SDK.MONITOR_STATE.HIDE_TRAY,

653

* SDK.MONITOR_STATE.BLOCK_DATA_BG.

654

655

== 5.9 Advertising systems ==

656

657

* Method that returns the IDs user profiles

658

659

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

660

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

661

662

663

MobigateSDK.get().enableIDsProfiles(true);

664

665

666

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

667

668

669

MobigateSDK.get().getIDsProfiles();

670

671

672

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

673

674

* Optional integration with AdOcean module from GemiusSDK

675

676

677

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

678

679

680

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

Sample usage:

FullScreenAd interstitial1 = new FullScreenAd(context, INTERSTITIAL1_PLACEMENT_ID);

685

interstitial1.setNumericalVariables(MobigateSDK.getAdOceanTargeting());

686

interstitial1.open();

687

688

689

Same applies to billboard adds.

690

691

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

692

693

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

694

695

* Mobigate user identifier,

696

* ANDROID_ID,

697

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

698

699

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

700

701

702

= 6. Testing SDK integration =

703

704

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

705

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

706

707

708

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