# \[Android]ビジュアルトラッキングを利用する

ペアリングしたデバイスから管理画面に対して送信した操作ログを利用して、イベントの発火条件を定義できます。

定義したイベント発火条件は各デバイスに反映されるため、アプリケーションをリリースすることなく、イベントの発火をコントロールすることが可能になります。

## 導入手順

1. Karte Gradle Plugin の適用\
   ビジュアルトラッキングを有効化するには、Gradle Plugin の設定が必要です。\
   ルートプロジェクトの `build.gradle` の `buildscript` ブロックに以下の記述を追加してください。\
   Karte Gradle Plugin は 最新バージョンの使用を推奨します。

{% code title="build.gradle" overflow="wrap" %}

```groovy
buildscript {
  // ...
  repositories {
    // ...
    mavenCentral()
    // ...
  }
  dependencies {
    classpath "io.karte.android:gradle-plugin:2.5.0"
    //...
  }
}
```

{% endcode %}

次にアプリの `build.gradle` を修正し、`apply plugin: 'com.android.application'` の下に `apply plugin: 'io.karte.android'` を追記してください。

{% code title="build.gradle" overflow="wrap" %}

```groovy
apply plugin: 'com.android.application'
apply plugin: 'io.karte.android'
```

{% endcode %}

### Android Gradle Pluginの動作確認済みバージョン

Android Gradle Plugin（`com.android.tools.build:gradle`）との組み合わせによる動作確認の状況は下記になります。

| Karte Gradle Plugin | Android Gradle Plugin |
| ------------------- | --------------------- |
| 2.5.0 ※, 2.5.1      | 3.6.0 \~ 8.0.0        |
| 2.4.0               | 3.1.0 \~ 7.4.1        |
| 2.3.0               | 3.1.0 \~ 4.2.1        |
| 2.2.0               | 3.1.0 \~ 4.0.1        |
| 2.1.0               | 3.1.0 \~ 4.0.1        |
| 2.0.0               | 3.1.0 \~ 3.6.4        |

※ 2.5.0ではJava 17で実行する際に `--add-opens=java.desktop/com.sun.beans.finder=ALL-UNNAMED` のオプション指定が必要です。2.5.1ではJava 17に対応しています。

{% hint style="warning" %}
**Instant Run 対応**

Instant Run には対応していません。\
開発時にビジュアルトラッキングを有効にする際は [Instant Runを無効化](https://developer.android.com/studio/run/index.html#disable-ir) してください。
{% endhint %}

{% hint style="warning" %}
**Jetpack Compose 対応**

現在のバージョンでは Jetpack Compose 上のタップイベントには対応していません。
{% endhint %}

2. `visualtracking` モジュールの追加\
   アプリの `build.gradle (app)` を任意のエディタで開き、`dependencies` ブロックに `visualtracking` モジュールを追加します。

{% code title="build.gradle" overflow="wrap" %}

```groovy
dependencies {
  implementation 'io.karte.android:visualtracking:2.+'
}
```

{% endcode %}

## 実装手順

### KARTE独自のカスタムURLスキームの設定

ペアリングのために、[カスタムURLスキームの指定](https://app.developers.karte.io/android-sdk-appendix/concepts-custom-url-scheme-android-sdk)が必要です。\
既にカスタムURLスキームがある（`intent-filter` 要素にアプリ固有のスキームが指定された Activity が `AndroidManifest.xml` に存在する）場合は、以下の手順は不要です。

カスタムURLスキームの設定が無い場合、ペアリング用のURLスキームに任意の文字列を指定可能です。\
`name` 属性に `"io.karte.android.Tracker.PairingUrlScheme"` を指定した `meta-data` 要素を追加し、値にURLスキームを設定してください。

{% code title="AndroidManifest.xml" overflow="wrap" %}

```xml
<application android:label="SampleApp" ...>
    <meta-data android:name="io.karte.android.Tracker.PairingUrlScheme" android:value="sampleapp"/>
    ...
</application>
```

{% endcode %}

## 動作確認

2点の動作が確認できれば問題なく動作していることが確認できます。

1. ペアリングの確認
2. 定義に基づいたイベントの送信が行われているか確認

ペアリングをはじめとした各種操作方法については、サポートサイトの [ビジュアルトラッキング](https://support.karte.io/post/7JbUVotDwZMvl6h3HL9Zt7) をご覧ください。

{% hint style="info" %}
**ペアリングの動作について**

ペアリング開始後、SDKはペアリングを維持するために一定間隔で通信を行います。\
なおアプリケーションのプロセスが終了した場合は、ペアリングは解除されます。
{% endhint %}


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://app.developers.karte.io/android-sdk/visual-tracking-android-sdk.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.