# PerfettoSdkHandshake

Artifact: [androidx.tracing:tracing-perfetto-handshake](https://developer.android.com/jetpack/androidx/releases/tracing) [View Source](https://cs.android.com/search?q=file:androidx/tracing/perfetto/handshake/PerfettoSdkHandshake.kt+class:androidx.tracing.perfetto.handshake.PerfettoSdkHandshake) Added in [1.0.1](https://developer.android.com/jetpack/androidx/releases/tracing#1.0.1)

*** ** * ** ***

<br />

```
public final class PerfettoSdkHandshake
```

<br />

*** ** * ** ***

Handshake implementation allowing to enable Perfetto SDK tracing in an app that enables it.

## Summary

| ### Nested types |
|---|
| `public sealed class https://developer.android.com/reference/androidx/tracing/perfetto/handshake/PerfettoSdkHandshake.LibrarySource` Provides means to sideload Perfetto SDK native binaries |

| ### Public constructors |
|---|
| `https://developer.android.com/reference/androidx/tracing/perfetto/handshake/PerfettoSdkHandshake#PerfettoSdkHandshake(kotlin.String,kotlin.Function1,kotlin.Function1)( @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/String.html targetPackage, @https://developer.android.com/reference/androidx/annotation/NonNull Function1<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/String.html, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/util/Map.html<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/String.html, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/String.html>> parseJsonMap, @https://developer.android.com/reference/androidx/annotation/NonNull Function1<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/String.html, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/String.html> executeShellCommand )` |

| ### Public methods |
|---|---|
| `final @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/tracing/perfetto/handshake/protocol/Response` | `https://developer.android.com/reference/androidx/tracing/perfetto/handshake/PerfettoSdkHandshake#disableTracingColdStart()()` Disables cold start tracing in the app if previously enabled by `https://developer.android.com/reference/androidx/tracing/perfetto/handshake/PerfettoSdkHandshake#enableTracingColdStart(kotlin.Boolean,androidx.tracing.perfetto.handshake.PerfettoSdkHandshake.LibrarySource)`. |
| `final @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/tracing/perfetto/handshake/protocol/Response` | `https://developer.android.com/reference/androidx/tracing/perfetto/handshake/PerfettoSdkHandshake#enableTracingColdStart(kotlin.Boolean,androidx.tracing.perfetto.handshake.PerfettoSdkHandshake.LibrarySource)( boolean persistent, https://developer.android.com/reference/androidx/tracing/perfetto/handshake/PerfettoSdkHandshake.LibrarySource librarySource )` Attempts to prepare cold startup tracing in the app. |
| `final @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/androidx/tracing/perfetto/handshake/protocol/Response` | `https://developer.android.com/reference/androidx/tracing/perfetto/handshake/PerfettoSdkHandshake#enableTracingImmediate(androidx.tracing.perfetto.handshake.PerfettoSdkHandshake.LibrarySource)( https://developer.android.com/reference/androidx/tracing/perfetto/handshake/PerfettoSdkHandshake.LibrarySource librarySource )` Attempts to enable tracing in the app. |

## Public constructors

### PerfettoSdkHandshake

Added in [1.0.1](https://developer.android.com/jetpack/androidx/releases/tracing#1.0.1)

```
public PerfettoSdkHandshake(
    @NonNull String targetPackage,
    @NonNull Function1<@NonNull String, @NonNull Map<@NonNull String, @NonNull String>> parseJsonMap,
    @NonNull Function1<@NonNull String, @NonNull String> executeShellCommand
)
```

| Parameters |
|---|---|
| `@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/String.html targetPackage` | package name of the target app |
| `@https://developer.android.com/reference/androidx/annotation/NonNull Function1<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/String.html, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/util/Map.html<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/String.html, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/String.html>> parseJsonMap` | function parsing a flat map in a JSON format into a `Map<String, String>` e.g. `"{ 'key 1': 'value 1', 'key 2': 'value 2' }"` -\>`mapOf("key 1" to "value 1", "key 2" to "value 2")` |
| `@https://developer.android.com/reference/androidx/annotation/NonNull Function1<@https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/String.html, @https://developer.android.com/reference/androidx/annotation/NonNull https://developer.android.com/reference/java/lang/String.html> executeShellCommand` | function allowing to execute `adb shell` commands on the target device For error handling, note that `https://developer.android.com/reference/androidx/tracing/perfetto/handshake/PerfettoSdkHandshake#parseJsonMap()` and `https://developer.android.com/reference/androidx/tracing/perfetto/handshake/PerfettoSdkHandshake#executeShellCommand()` will be called on the same thread as `https://developer.android.com/reference/androidx/tracing/perfetto/handshake/PerfettoSdkHandshake#enableTracingImmediate(androidx.tracing.perfetto.handshake.PerfettoSdkHandshake.LibrarySource)` and `https://developer.android.com/reference/androidx/tracing/perfetto/handshake/PerfettoSdkHandshake#enableTracingColdStart(kotlin.Boolean,androidx.tracing.perfetto.handshake.PerfettoSdkHandshake.LibrarySource)`. |

## Public methods

### disableTracingColdStart

Added in [1.0.1](https://developer.android.com/jetpack/androidx/releases/tracing#1.0.1)

```
public final @NonNull Response disableTracingColdStart()
```

Disables cold start tracing in the app if previously enabled by `https://developer.android.com/reference/androidx/tracing/perfetto/handshake/PerfettoSdkHandshake#enableTracingColdStart(kotlin.Boolean,androidx.tracing.perfetto.handshake.PerfettoSdkHandshake.LibrarySource)`.

No-op if cold start tracing was not enabled in the app, or if it was enabled in the non-`persistent` mode and the app has already been started at least once.

The function initially enables the app process (if not already enabled), but leaves it in a terminated state after executing.

| See also |
|---|---|
| `https://developer.android.com/reference/androidx/tracing/perfetto/handshake/PerfettoSdkHandshake#enableTracingColdStart(kotlin.Boolean,androidx.tracing.perfetto.handshake.PerfettoSdkHandshake.LibrarySource)` |   |

### enableTracingColdStart

Added in [1.0.1](https://developer.android.com/jetpack/androidx/releases/tracing#1.0.1)

```
public final @NonNull Response enableTracingColdStart(
    boolean persistent,
    PerfettoSdkHandshake.LibrarySource librarySource
)
```

Attempts to prepare cold startup tracing in the app.

Leaves the app process in a terminated state.

| Parameters |
|---|---|
| `boolean persistent` | if set to true, cold start tracing mode is persisted between app runs and must be cleared using `https://developer.android.com/reference/androidx/tracing/perfetto/handshake/PerfettoSdkHandshake#disableTracingColdStart()`. Otherwise, cold start tracing is enabled only for the first app start since enabling. While persistent mode reduces some overhead of setting up tracing, it recommended to use non-persistent mode as it does not pose the risk of leaving cold start tracing persistently enabled in case of a failure to clean-up with `https://developer.android.com/reference/androidx/tracing/perfetto/handshake/PerfettoSdkHandshake#disableTracingColdStart()`. |
| `https://developer.android.com/reference/androidx/tracing/perfetto/handshake/PerfettoSdkHandshake.LibrarySource librarySource` | optional AAR or an APK containing `libtracing_perfetto.so` |

### enableTracingImmediate

Added in [1.0.1](https://developer.android.com/jetpack/androidx/releases/tracing#1.0.1)

```
public final @NonNull Response enableTracingImmediate(
    PerfettoSdkHandshake.LibrarySource librarySource
)
```

Attempts to enable tracing in the app. It will wake up (or start) the app process, so it will act as warm/hot tracing. For cold tracing see `https://developer.android.com/reference/androidx/tracing/perfetto/handshake/PerfettoSdkHandshake#enableTracingColdStart(kotlin.Boolean,androidx.tracing.perfetto.handshake.PerfettoSdkHandshake.LibrarySource)`

Note: if the app process is not running, it will be launched making the method a bad choice for cold tracing (use `https://developer.android.com/reference/androidx/tracing/perfetto/handshake/PerfettoSdkHandshake#enableTracingColdStart(kotlin.Boolean,androidx.tracing.perfetto.handshake.PerfettoSdkHandshake.LibrarySource)` instead.

| Parameters |
|---|---|
| `https://developer.android.com/reference/androidx/tracing/perfetto/handshake/PerfettoSdkHandshake.LibrarySource librarySource` | optional AAR or an APK containing `libtracing_perfetto.so` |