# \[Android]SDKを導入する

## 前提条件

KARTE Android SDKを導入するための前提条件に関しては、[公開リポジトリのREADME](https://github.com/plaidev/karte-android-sdk?tab=readme-ov-file#requirements)をご参照ください。

## 導入手順

### 1. SDKをアプリに追加する

1. リポジトリの追加 ルートプロジェクトの `build.gradle` を任意のエディタで開き、`allprojects > repositories` ブロックに mavenCentral リポジトリを追加します。

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

```groovy
allprojects {
  repositories {
    // ...
    mavenCentral()
  }
}
```

{% endcode %}

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

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

```groovy
dependencies {
  implementation 'io.karte.android:core:2.+' //イベントトラッキング機能を提供します。
  implementation 'io.karte.android:inappmessaging:2.+' //アプリ内メッセージ機能を提供します。
  implementation 'io.karte.android:notifications:2.+' //プッシュ通知の受信および効果測定機能を提供します。
  implementation 'io.karte.android:variables:2.+' //設定値配信機能を提供します。
  implementation 'io.karte.android:visualtracking:2.+' //ビジュアルトラッキング機能を提供します。※ 別途Gradle Pluginが必要です。
  implementation 'io.karte.android:debugger:1.+' //SDKイベントデバッガー機能を提供します。
}
```

{% endcode %}

KARTE SDKでは機能毎にモジュールを提供しております。\
利用する機能に応じて、部分的にモジュールを導入することが可能です。

なお core 導入は必須です。

各モジュールの詳細については、[利用可能なモジュール一覧](/android-sdk-appendix/appendix-module-android-sdk.md)をご確認ください。

{% hint style="info" %}
**各モジュールのバージョンについて**

各モジュールは適宜バグ修正や機能追加をおこなっています。\
バージョンを固定する際は、最新のバージョンを指定してください。\
最新バージョンは[リリースノート](/android-sdk/release-notes-android-sdk.md)にて確認できます。
{% endhint %}

### 2. 設定ファイルをプロジェクトに追加する

SDKの初期化に必要な値（アプリケーションキーなど）が定義された設定ファイルをプロジェクトに追加します。

1. 管理画面から設定ファイルをダウンロードする\
   設定ファイルのダウンロード方法については[サポートサイト](https://support.karte.io/post/SRlsXvrikIKjpZcfahGdc)をご覧ください。
2. 設定ファイルをプロジェクトに配置する\
   設定ファイルをプロジェクトのリソースに追加します。\
   該当するビルドバリアントの `res/values` ディレクトリに配置してください。

### 3. SDKの初期化コードを追加する

次にアプリケーションにSDKの初期化コードを追加します。

1. SDKのインポート宣言を追加 `android.app.Application` クラスを継承したクラスがあるファイルの先頭にインポート宣言を追加します。

{% tabs %}
{% tab title="Kotlin" %}
{% code overflow="wrap" %}

```kotlin
import io.karte.android.KarteApp
```

{% endcode %}
{% endtab %}

{% tab title="Java" %}
{% code overflow="wrap" %}

```java
import io.karte.android.KarteApp;
```

{% endcode %}
{% endtab %}
{% endtabs %}

2. SDKの初期化コードを追加 `onCreate` メソッド内に初期化コードを追加します。

{% hint style="warning" %}
**設定ファイルによるSDKの初期化について**

※設定ファイルによるSDK初期化は Android SDK v2.8.0 以上から利用できます。 古いSDKを利用している場合は `KarteApp.setup(context: appKey)` メソッドを利用して初期化してください。
{% endhint %}

{% tabs %}
{% tab title="Kotlin" %}
{% code title="YourApplication.kt" overflow="wrap" %}

```kotlin
class YourApplication : Application() {
  override fun onCreate() {
    super.onCreate()
    KarteApp.setup(this)
  }
}
```

{% endcode %}
{% endtab %}

{% tab title="Java" %}
{% code title="YourApplication.java" overflow="wrap" %}

```java
public class YourApplication extends Application {
  @Override
  public void onCreate() {
    super.onCreate();
    KarteApp.setup(this);
  }
}
```

{% endcode %}
{% endtab %}
{% endtabs %}

{% hint style="warning" %}
**アプリケーションキーについて**

初期化時に指定するアプリケーションキー（Application Key）は、KARTE管理画面に記載されているAPIキーとは異なります。取得方法は[アプリケーションキーの確認方法](https://support.karte.io/post/1PbomDUORPoCrcvos2rq3T#1-0:~:text=%E3%82%A2%E3%83%97%E3%83%AA%E3%82%B1%E3%83%BC%E3%82%B7%E3%83%A7%E3%83%B3%E3%82%AD%E3%83%BC%E3%81%AE,Application%20Key%E3%81%A7%E3%81%99%E3%80%82)をご確認ください。
{% endhint %}

{% hint style="danger" %}
**初期化について**

初期化メソッドは必ず `Application.onCreate()` で呼び出してください。`Activity.onCreate()` で呼び出した場合は正常に動作しません。

また適切な初期化が行われない場合には`native_app_open`等のイベント発生が阻害される可能性があります。
{% endhint %}

{% hint style="danger" %}
**isEdgeToEdgeEnabledオプションについて**

InAppMessaging 2.23.0以降ではisEdgeToEdgeEnabled というオプションが追加されています。 Edge to Edge環境下で利用する場合、このオプションの有効化が推奨されます。

参考: [targetSdkVersion 35以降のAndroid環境におけるEdge to Edge対応についての注意事項](/app-faq/notes-for-android-environments-with-target-sdk-version-35-later.md)
{% endhint %}

### 3. カスタムURLスキームをハンドルする

KARTE for App独自の一部機能の利用に必要な実装です。ホーム画面や、KARTEで頻度高く接客を表示することが想定される画面でご対応ください。

設定方法については [カスタムURLスキームを設定する](/android-sdk-appendix/concepts-custom-url-scheme-android-sdk.md) をご覧ください。

※launchMode に "singleTop" などを指定したActivityではintentが更新されないため、アプリがバックグラウンドにある状態ではカスタムURLスキームのハンドリングが正しく動作しない可能性があります。このような場合での対応方法については[再開されるActivityに対応する](/android-sdk-appendix/appendix-relaunch-activity-android-sdk.md) をご確認ください。

## トラブルシューティング

SDK導入時にビルドエラーが発生した場合は、[FAQ: SDKを導入するとビルドエラーが起きる](/app-faq/sdk-build-error.md) を参考にしてください。

**What’s Next**

SDKの導入が完了したら、次はイベントトラッキングの実装を行いましょう。


---

# 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/setup-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.