<commit_before>[![N|Solid](https://ebuilder.com/wp-content/uploads/2017/02/ebuilder-effortless-logo.png)](https://ebuilder.com/)

- [Android compatibility](#android-compatibility)
- [Project Setup](#project-setup)
  - [Permissions](#permissions)
  - [Gradle Dependencies](#gradle-dependencies)
  - [Proguard](#proguard)
  - [Content Provider configuration](#content-provider-configuration)
- [Initialization](#initialization)
  - [Associating collected data with a user/device identity](#associating-collected-data-with-a-userdevice-identity)
- [Modes supported by DDC](#modes-supported-by-ddc)
- [On demand trigger](#on-demand-trigger)
  - [Usage](#usage)
- [Scheduled triggers](#scheduled-triggers)
  - [Usage](#usage-1)

## Android compatibility

Minimum supported [Android SDK version](https://source.android.com/source/build-numbers) is 16 (4.1.x / Jelly Bean).

## Project Setup

### Permissions
The *Device Data Collector* (DDC) SDK will not ask for any permissions; it's a host application's responsibility to request them. Library *support-v4* has been included only to check permissions state.

DDC SDK doesn't need any permissions in order to run. If no permissions are set by the host application, DDC will only collect data for which permissions are not required.

However, there are some permissions that improve data quality if already granted to the host application:

| Permission                                | Description                                                   | Runtime |
| ----------------------------------------- | ------------------------------------------------------------  | ------- |
| android.permission.READ_PHONE_STATE       | Retrieve device ids, network operator names                   | no      |
| android.permission.ACCESS_WIFI_STATE      | Retrieve WiFi status                                          | no      |
| android.permission.ACCESS_NETWORK_STATE   | Retrieve network status                                      | no      |
| android.permission.BLUETOOTH              | Retrieve information about Bluetooth adapter and paired devices | no      |
| android.permission.INTERNET               | To enable SDK to make network call                           | no      |
| android.permission.RECEIVE_BOOT_COMPLETED | Used for scheduling jobs to run services-on-demand           | no      |
| android.permission.WAKE_LOCK              | Used for scheduling jobs to run services-on-demand           | no      |



### Gradle Dependencies
Add the following repository:
```
allprojects {
    repositories {
        maven {
            url "https://artifacts.ebuilder.io/repository/ebuilder-external-android/"
        }
    }
}

```

Add DDC SDK:

```groovy
dependencies {
    implementation "io.ebuilder.mobile.services:ddc-sdk:192.168.127.12"
}
```

**Note**: The DDC SDK has [dependencies of its own](https://artifacts-int.ebuilder.io/repository/ebuilder-maven/io/ebuilder/mobile/services/ddc-sdk/1.2.0.255/ddc-sdk-1.2.0.255.pom). If you run into build or runtime issues because your project depends on an older version of the Android support library, you can exclude the one required by DDC: 

```groovy
dependencies {
    implementation ("io.ebuilder.mobile.services:ddc-sdk:192.168.127.12") {
        exclude group: "com.android.support"
    }
}
```

###  

### Proguard

In case your app has [proguard](https://developer.android.com/studio/build/shrink-code) rules enabled you need to ensure that DDC SDK classes are excluded from the proguard processing.


Adjust your **proguard-rules.pro** file with the following lines:

```
-keep class io.ebuilder.mobile.services.** { *; }
-keep interface io.ebuilder.mobile.services.** { *; }
```



### Content Provider configuration

The SDK is using **Content Providers** to manage access to locally stored data. For more on Content Providers and their advantages see the [Android documentation](https://developer.android.com/guide/topics/providers/content-providers). 

The host app is required to specify a unique app content uri. DDC reads this value as the attribute **data_content_provider_authority** that can be configured in *build.gradle*

```groovy
android {
    compileSdkVersion 27
    buildToolsVersion "27.0.3"

    defaultConfig {
        applicationId "com.company.app"
        minSdkVersion 16
        targetSdkVersion 27
        versionCode 1
        versionName "1.0"

        resValue "string", "data_content_provider_authority", "${applicationId}.ddc"
    }
}
```



## Initialization

```java
DeviceDataCollector ddc = DeviceDataCollector.getDefault(context, "YOUR_LICENSE_KEY");
```

DeviceDataCollector.getDefault(...) has the following mandatory arguments:
* *context* (Context) : application context
* *licenseKey* (String) : the licence key provided by eBuilder

Enable SDK logging:

```java
ddc.loggingEnabled(true);
```

#### Associating collected data with a user/device identity
The following instance methods can be used to optionally provide additional user/device identifiers:

| Name           | Description                                                  |      |
| -------------- | ------------------------------------------------------------ | ---- |
| advertisingID  | The [Android advertising ID](https://developers.google.com/android/reference/com/google/android/gms/ads/identifier/package-summary) of a device. |      |
| externalUserID | The host application's user identity. For example a (unique) user name, a user ID, an e-mail - or a hash thereof. |      |
| phoneNumber    | The user's phone number.                                     |      |

Example:

```java
ddc.externalUserID("c23911a2-c455-4a59-96d0-c6fea09176b8"); 
ddc.phoneNumber("+1234567890");
ddc.advertisingId(adID);
```



## Modes supported by DDC

* **On demand trigger**: Host app explicitly calls DDC to collect data whenever desired.<commit_msg>Add import.<commit_after>[![N|Solid](https://ebuilder.com/wp-content/uploads/2017/02/ebuilder-effortless-logo.png)](https://ebuilder.com/)

- [Android compatibility](#android-compatibility)
- [Project Setup](#project-setup)
  - [Permissions](#permissions)
  - [Gradle Dependencies](#gradle-dependencies)
  - [Proguard](#proguard)
  - [Content Provider configuration](#content-provider-configuration)
- [Initialization](#initialization)
  - [Associating collected data with a user/device identity](#associating-collected-data-with-a-userdevice-identity)
- [Modes supported by DDC](#modes-supported-by-ddc)
- [On demand trigger](#on-demand-trigger)
  - [Usage](#usage)
- [Scheduled triggers](#scheduled-triggers)
  - [Usage](#usage-1)

## Android compatibility

Minimum supported [Android SDK version](https://source.android.com/source/build-numbers) is 16 (4.1.x / Jelly Bean).

## Project Setup

### Permissions
The *Device Data Collector* (DDC) SDK will not ask for any permissions; it's a host application's responsibility to request them. Library *support-v4* has been included only to check permissions state.

DDC SDK doesn't need any permissions in order to run. If no permissions are set by the host application, DDC will only collect data for which permissions are not required.

However, there are some permissions that improve data quality if already granted to the host application:

| Permission                                | Description                                                   | Runtime |
| ----------------------------------------- | ------------------------------------------------------------  | ------- |
| android.permission.READ_PHONE_STATE       | Retrieve device ids, network operator names                   | no      |
| android.permission.ACCESS_WIFI_STATE      | Retrieve WiFi status                                          | no      |
| android.permission.ACCESS_NETWORK_STATE   | Retrieve network status                                      | no      |
| android.permission.BLUETOOTH              | Retrieve information about Bluetooth adapter and paired devices | no      |
| android.permission.INTERNET               | To enable SDK to make network call                           | no      |
| android.permission.RECEIVE_BOOT_COMPLETED | Used for scheduling jobs to run services-on-demand           | no      |
| android.permission.WAKE_LOCK              | Used for scheduling jobs to run services-on-demand           | no      |



### Gradle Dependencies
Add the following repository:
```
allprojects {
    repositories {
        maven {
            url "https://artifacts.ebuilder.io/repository/ebuilder-external-android/"
        }
    }
}

```

Add DDC SDK:

```groovy
dependencies {
    implementation "io.ebuilder.mobile.services:ddc-sdk:1.2.0.255"
}
```

**Note**: The DDC SDK has [dependencies of its own](https://artifacts-int.ebuilder.io/repository/ebuilder-maven/io/ebuilder/mobile/services/ddc-sdk/1.2.0.255/ddc-sdk-1.2.0.255.pom). If you run into build or runtime issues because your project depends on an older version of the Android support library, you can exclude the one required by DDC: 

```groovy
dependencies {
    implementation ("io.ebuilder.mobile.services:ddc-sdk:1.2.0.255") {
        exclude group: "com.android.support"
    }
}
```

###  

### Proguard

In case your app has [proguard](https://developer.android.com/studio/build/shrink-code) rules enabled you need to ensure that DDC SDK classes are excluded from the proguard processing.


Adjust your **proguard-rules.pro** file with the following lines:

```
-keep class io.ebuilder.mobile.services.** { *; }
-keep interface io.ebuilder.mobile.services.** { *; }
```



### Content Provider configuration

The SDK is using **Content Providers** to manage access to locally stored data. For more on Content Providers and their advantages see the [Android documentation](https://developer.android.com/guide/topics/providers/content-providers). 

The host app is required to specify a unique app content uri. DDC reads this value as the attribute **data_content_provider_authority** that can be configured in *build.gradle*

```groovy
android {
    compileSdkVersion 27
    buildToolsVersion "27.0.3"

    defaultConfig {
        applicationId "com.company.app"
        minSdkVersion 16
        targetSdkVersion 27
        versionCode 1
        versionName "1.0"

        resValue "string", "data_content_provider_authority", "${applicationId}.ddc"
    }
}
```



## Initialization

Import DDC:

```java
import io.ebuilder.mobile.services.DeviceDataCollector;
```

Create an instance:

```java
DeviceDataCollector ddc = DeviceDataCollector.getDefault(context, "YOUR_LICENSE_KEY");
```

DeviceDataCollector.getDefault(...) has the following mandatory arguments:
* *context* (Context) : application context
* *licenseKey* (String) : the licence key provided by eBuilder

Enable SDK logging (optional):

```java
ddc.loggingEnabled(true);
```

#### Associating collected data with a user/device identity
The following instance methods can be used to optionally provide additional user/device identifiers:

| Name           | Description                                                  |
| -------------- | ------------------------------------------------------------ |
| advertisingID  | The [Android advertising ID](https://developers.google.com/android/reference/com/google/android/gms/ads/identifier/package-summary) of a device. |
| externalUserID | The host application's user identity. For example a (unique) user name, a user ID, an e-mail - or a hash thereof. |
| phoneNumber    | The user's phone number.                                     |

Example:

```java
ddc.externalUserID("c23911a2-c455-4a59-96d0-c6fea09176b8"); 
ddc.phoneNumber("+1234567890");
ddc.advertisingId(adID);
```



## Modes supported by DDC

* **On demand trigger**: Host app explicitly calls DDC to collect data whenever desired.
{'fraction_non_alphanumeric': 0.13387028401865197, 'fraction_numerical': 0.014582450190758796, 'mean_word_length': 2.7071024512884976, 'pattern_counts': {'":': 0, '<': 3, '<?xml version=': 0, '>': 3, 'https://': 16, 'lorem ipsum': 0, 'www.': 0, 'xml': 0}, 'pii_count': 8, 'substrings_counts': 0, 'word_list_counts': {'cursed_substrings.json': 23, 'profanity_word_list.json': 0, 'sexual_word_list.json': 0, 'zh_pornsignals.json': 0}}
{'dir': 'git-commits-cleaned', 'id': '1153394', 'n_tokens_mistral': 3364, 'n_tokens_neox': 3093, 'n_words': 933}