> For the complete documentation index, see [llms.txt](https://app.developers.karte.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://app.developers.karte.io/android-sdk/visual-tracking-android-sdk.md).

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

{% hint style="danger" %}
**ビジュアルトラッキングの新規提供終了について**

ビジュアルトラッキングは、2026年9月30日をもって新規提供を終了します。\
2026年10月1日以降は、本機能を新たに利用開始することはできません。\
なお、2026年9月30日までに利用を開始されている場合は、引き続きご利用いただけます。
{% endhint %}

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

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

## 導入手順

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スキームの指定](/android-sdk-appendix/concepts-custom-url-scheme-android-sdk.md)が必要です。\
既にカスタム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 %}