Skip to content

Commit

Permalink
Merge pull request #459 from DataDog/mconstantin/rumm-943/update-docs…
Browse files Browse the repository at this point in the history 
…-for-new-initialisation

RUMM-943 Update the docs following the new API for SDK initialisation
  • Loading branch information
@xgouchet
xgouchet authored Jan 18, 2021
2 parents d9e6060 + 56f0bf6 commit dcb5a63
Show file tree
Hide file tree
Showing 6 changed files with 310 additions and 150 deletions.
4 changes: 2 additions & 2 deletions docs/README.md
View file
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
# Datadog Android SDK documentation

This folder has dedicated documentation for:

* [Initialize the SDK](sdk_initialization.md)
* [Collect and send logs from your Android application to Datadog](log_collection.md).
* [Trace your Android application](trace_collection.md).
* [Monitoring your Android application](rum_collection.md).
Expand All @@ -11,4 +11,4 @@ This folder has dedicated documentation for:
* [Timber API integration](timber_integration.md).
* [Migrating from earlier versions to the v1.0 of the dd-sdk-android](Migrating_To_1.0.0.md).
* [SDK Perfomance](sdk_performance.md)
* [SDK Benchmarks](sdk_benchmarks.md)
* [SDK Benchmarks](sdk_benchmarks.md)
107 changes: 56 additions & 51 deletions docs/log_collection.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -8,8 +8,6 @@ Send logs to Datadog from your Android applications with [Datadog's `dd-sdk-andr
* Record real client IP addresses and User-Agents.
* Optimized network usage with automatic bulk posts.

**Note**: The `dd-sdk-android` library supports all Android versions from API level 19 (KitKat).

## Setup

1. Add the Gradle dependency by declaring the library as a dependency in your `build.gradle` file:
Expand All @@ -24,56 +22,64 @@ Send logs to Datadog from your Android applications with [Datadog's `dd-sdk-andr
}
```
2. Initialize the library with your application context, [tracking consent][7], and the [Datadog client token][2] and Application ID generated when you create a new RUM application in the Datadog UI (see [Getting Started with Android RUM Collection][6] for more information). For security reasons, you must use a client token: you cannot use [Datadog API keys][3] to configure the `dd-sdk-android` library as they would be exposed client-side in the Android application APK byte code. For more information about setting up a client token, see the [client token documentation][2]:
{{< tabs >}}
{{% tab "US" %}}
```kotlin
class SampleApplication : Application() {
override fun onCreate() {
super.onCreate()
val config = DatadogConfig.Builder("<CLIENT_TOKEN>", "<ENVIRONMENT_NAME>", "<APPLICATION_ID>")
.build()
Datadog.initialize(this, trackingConsent, config)
2. Initialize the library with your application context, tracking consent, and the [Datadog client token][2] and Application ID generated when you create a new RUM application in the Datadog UI (see [Getting Started with Android RUM Collection][6] for more information). For security reasons, you must use a client token: you cannot use [Datadog API keys][3] to configure the `dd-sdk-android` library as they would be exposed client-side in the Android application APK byte code. For more information about setting up a client token, see the [client token documentation][2]:
{{< tabs >}}
{{% tab "US" %}}
```kotlin
class SampleApplication : Application() {
override fun onCreate() {
super.onCreate()
val configuration = Configuration.Builder().build()
val credentials = Credentials(<CLIENT_TOKEN>,<ENV_NAME>,<APP_VARIANT_NAME>,<APPLICATION_ID>)
Datadog.initialize(this, credentials, configuration, trackingConsent)
}
}
}
```

{{% /tab %}}
{{% tab "EU" %}}

```kotlin
class SampleApplication : Application() {
override fun onCreate() {
super.onCreate()

val config = DatadogConfig.Builder("<CLIENT_TOKEN>", "<ENVIRONMENT_NAME>", "<APPLICATION_ID>")
.useEUEndpoints()
.build()
Datadog.initialize(this, trackingConsent, config)
```
{{% /tab %}}
{{% tab "EU" %}}
```kotlin
class SampleApplication : Application() {
override fun onCreate() {
super.onCreate()
val configuration = Configuration.Builder()
.useEUEndpoints()
.build()
val credentials = Credentials(<CLIENT_TOKEN>,<ENV_NAME>,<APP_VARIANT_NAME>,<APPLICATION_ID>)
Datadog.initialize(this, credentials, configuration, trackingConsent)
}
}
```
{{% /tab %}}
{{< /tabs >}}

To be compliant with the GDPR regulation, the SDK requires the tracking consent value at initialization.
The tracking consent can be one of the following values:
* `TrackingConsent.PENDING`: The SDK starts collecting and batching the data but does not send it to the data
collection endpoint. The SDK waits for the new tracking consent value to decide what to do with the batched data.
* `TrackingConsent.GRANTED`: The SDK starts collecting the data and sends it to the data collection endpoint.
* `TrackingConsent.NOT_GRANTED`: The SDK does not collect any data. You will not be able to manually send any logs, traces, or
RUM events.

To update the tracking consent after the SDK is initialized, call: `Datadog.setTrackingConsent(<NEW CONSENT>)`.
The SDK changes its behavior according to the new consent. For example, if the current tracking consent is `TrackingConsent.PENDING` and you update it to:
* `TrackingConsent.GRANTED`: The SDK sends all current batched data and future data directly to the data collection endpoint.
* `TrackingConsent.NOT_GRANTED`: The SDK wipes all batched data and does not collect any future data.

Note that in the credentials required for initialization, your application variant name is also required. This is important because it enables the right proguard `mapping.txt` file to be automatically uploaded at build time. This allows a Datadog dashboard to de-obfuscate the stack traces.

Use the utility method `isInitialized` to check if the SDK is properly initialized:

```kotlin
if(Datadog.isInitialized()){
// your code here
}
}
```

{{% /tab %}}
{{< /tabs >}}

There is also a utility method which gives you the current state of the SDK. You can use this to check if it was properly initialized or not:

```kotlin
if(Datadog.isInitialized()){
// your code here
}
```

When writing your application, you can enable development logs. All internal messages in the library with a priority equal or higher than the provided level are then logged to Android's Logcat.

```kotlin
Datadog.setVerbosity(Log.INFO)
```

```
When writing your application, you can enable development logs by calling the `setVerbosity` method. All internal messages in the library with a priority equal to or higher than the provided level are then logged to Android's Logcat:
```kotlin
Datadog.setVerbosity(Log.INFO)
```

3. Configure the Android Logger:

```kotlin
Expand Down Expand Up @@ -244,4 +250,3 @@ If your existing codebase is using Timber, you can forward all those logs to Da
[4]: https://docs.datadoghq.com/logs/processing/attributes_naming_convention/
[5]: https://docs.datadoghq.com/tagging/
[6]: https://docs.datadoghq.com/real_user_monitoring/android/?tab=us
[7]: gdpr.md
39 changes: 31 additions & 8 deletions docs/native_crash_collection.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -19,15 +19,38 @@ dependencies {
}
```

### Plugins

1. The NDKCrashReporterPlugin handles the crash signals at the native level and reports them as errors by adding more explicit information (for example: backtrace, signal name, signal relevant error message) in the Datadog logs dashboard:
Initialize the library with your application context, tracking consent, and the [Datadog client token][1] and Application ID generated when you create a new RUM application in the Datadog UI (see [Getting Started with Android RUM Collection][3] for more information). For security reasons, you must use a client token: you cannot use [Datadog API keys][2] to configure the `dd-sdk-android` library as they would be exposed client-side in the Android application APK byte code. For more information about setting up a client token, see the [client token documentation][1]:

```kotlin
class SampleApplication : Application() {
override fun onCreate() {
super.onCreate()

val configuration = Configuration.Builder()
.addPlugin(NDKCrashReporterPlugin(), Feature.CRASH)
.build()
val credentials = Credentials(<CLIENT_TOKEN>,<ENV_NAME>,<APP_VARIANT_NAME>,<APPLICATION_ID>)
Datadog.initialize(this, credentials, configuration, trackingConsent)
}
}
```
To be compliant with the GDPR regulation, the SDK requires the tracking consent value at initialization.
The tracking consent can be one of the following values:

val config = DatadogConfig.Builder("<CLIENT_TOKEN>", "<ENVIRONMENT_NAME>", "<APPLICATION_ID>")
.addPlugin(NDKCrashReporterPlugin(), Feature.CRASH)
.build()
Datadog.initialize(this, config)
* `TrackingConsent.PENDING`: The SDK starts collecting and batching the data but does not send it to the data
collection endpoint. The SDK waits for the new tracking consent value to decide what to do with the batched data.
* `TrackingConsent.GRANTED`: The SDK starts collecting the data and sends it to the data collection endpoint.
* `TrackingConsent.NOT_GRANTED`: The SDK does not collect any data. You will not be able to manually send any logs, traces, or
RUM events.

```
To update the tracking consent after the SDK is initialized, call: `Datadog.setTrackingConsent(<NEW CONSENT>)`.
The SDK changes its behavior according to the new consent. For example, if the current tracking consent is `TrackingConsent.PENDING` and you update it to:

* `TrackingConsent.GRANTED`: The SDK sends all current batched data and future data directly to the data collection endpoint.
* `TrackingConsent.NOT_GRANTED`: The SDK wipes all batched data and does not collect any future data.

Note that in the credentials required for initialization, your application variant name is also required. This is important because it enables the right proguard `mapping.txt` file to be automatically uploaded at build time. This allows a Datadog dashboard to de-obfuscate the stack traces.

[1]: https://docs.datadoghq.com/account_management/api-app-keys/#client-tokens
[2]: https://docs.datadoghq.com/account_management/api-app-keys/#api-keys
[3]: https://docs.datadoghq.com/real_user_monitoring/android/?tab=us
Loading

0 comments on commit dcb5a63

Please sign in to comment.