変更履歴ガイドご利用ガイドコーポレートサイト

Android版SDK 導入手順

本ドキュメントはアプリケーションがKotlinで記述されている前提で記述されていますが、Javaで記述されたアプリケーションからも同等の機能を利用することができます。

Suggest Edits

SDKがサポートするアプリケーション

現時点でAndroid版SDKがサポートする環境は以下のとおりです。

  • minSdkVersion 21以降
  • androidx Fragmentを使用してUIを構築している
  • Gradleによるビルドをおこなっている

以下のアプリケーションはサポートしていません。

  • Support Library の v7 appcompat でUIが構築されている
  • Jetpack ComposeでUIが構築されている
  • WebViewでUIが構築されている

SDKでできること

アプリケーションを使ったユーザーの行動イベントをサーバーに送信し、サーバーで設定された接客定義に従い任意の画面にダイアログを表示して接客を行うことができます。

SDKの仕組み

Android版SprocketSDKでは、AndroidのアプリケーションプロジェクトにSprocketSDK GradlePluginを組み込み、このプラグインが必要なSprocketSDKライブラリの組み込みを行います。

SDKの組み込み

SprocketSDKの組み込みはアプリケーションプロジェクトに対して以下のことを行います。

  • リポジトリの追加
  • プラグインの適用
  • サービスID, APIキーの設定
  • SprocketSDKインスタンスの取得
  • ログイン連携
  • 行動イベント送信
  • (option)deeplink対応

リポジトリの追加

projectのルートディレクトリにある settings.gradleで、SprocketSDK Gradle pluginと SprocketSDKライブラリのリポジトリの追加を行います。

pluginManagement {
repositories {
    gradlePluginPortal()
    google()
    mavenCentral()
    // ↓　これを追加
    maven { url '<SprocketSDKプラグインリポジトリのURL>' }
}
}
dependencyResolutionManagement {
repositoriesMode.set(RepositoriesMode.FAIL_ON_PROJECT_REPOS)
repositories {
    google()
    mavenCentral()
    // ↓　これを追加(こちらはプラグインが自動的に追加するよう変更される可能性あり)
    maven { url '<SprocketSDKライブラリリポジトリのURL>' }
}
}
...

プラグインの適用

アプリケーションのディレクトリのbuild.gradle(通常は app/build.gradle)にプラグインを適用します。

plugins {
id 'com.android.application'
id 'org.jetbrains.kotlin.android'
// ↓　この行を追加する
id 'bz.sprocket.sprocketsdk' version '0.1'
}
...

サービスID, APIキーの設定

アプリケーションのAndroidManifest.xml (app/src/main/AndroidManifest.xml)に、metaタグを用いてサービスIDとAPIキーを登録します。サービスIDの android:nameはbz.sprocket.service_id、APIキーの android:nameはbz.sprocket.api_keyです。

<manifest ... >
<application ... >
...
    <meta-data
        android:name="bz.sprocket.service_id"
        android:value="<サービスID>" />
    <meta-data
        android:name="bz.sprocket.api_key"
        android:value="<APIキー>" />

</application>

SprocketSDKの初期化

SprocketSDKは、アプリケーション起動時に自動的に初期化が行われます。

ただし特別な設定を行いたい場合などでは、自動的な初期化を無効化し手動で初期化を行います。手動での初期化の手順は後述します。

SprocketSDKインスタンスの取得

SprocketSDKは、SpSdk型のオブジェクトを通して様々な機能にアクセスします。

SprocketSDKの初期化が行われている状態であれば、以下のコードでSpSdkインスタンスを取得できます。

val sdk = SpSdk.instance

ログイン連携

アプリケーションにおいてログインが行われた場合、以下のようにログインを行います。

// ログインするとき
SpSdk.instance.loggedIn("<ユーザーID>", parameters)

// ログアウトするとき
SpSdk.instance.logout()

ログイン連携を行うことにより、ログイン情報を接客定義で利用できるようになります。

行動イベント送信

接客定義において、ユーザーが特定の画面を表示したことや特定の動作を行ったことを表示条件に利用する場合は、条件に使用する行動イベントを送信する必要があります。

行動イベントにはSDKにより自動的に送られるものと、アプリがSDKの機能を利用して手動で送るものが存在します。

自動送信

アプリケーションがフォアグラウンド状態になった際、フォアグラウンドになったことを示す行動イベントを自動的に送信します。イベント名は appResumed です。

手動送信

手動送信では、アプリ内で実行する処理に応じて任意の行動イベントを送信することができます。具体的には、特定の画面が表示されたことや特定の機能が実行されたことを意味する行動イベントが考えられます。

以下のコードにより、Sprocketのサーバーに対して行動イベントを送信することができます。

SpSdk.instance.sendAppActivity("<イベント名>", mapOf("<パラメーターキー>" to "<パラメータ値>"))

具体的には以下のようなコードです。

SpSdk.instance.sendAppActivity("showItemDetail", mapOf("itemId" to item.id.toString()))

接客UIからの画面遷移

SprocketSDKでは、接客UIからの画面遷移にdeeplinkを使用します。

接客定義において遷移先をdeeplinkで指定することで、接客UIから、アプリケーション内の任意の画面へ遷移することができます。

手動でのSprocketSDKの初期化

特殊な設定により初期化する場合など、自動的な初期化を行いたくない場合はAndroidManifest.xmlにmetaタグを記述することで自動的な初期化を無効化します。

<manifest ... >
<application ... >
...
    <meta-data
        android:name="bz.sprocket.auto_init_enabled"
        android:value="false" />
</application>

Flutterに対応するには

ここではSprocketSDKをFlutterで対応するために追加した機能について記載します。SprocketSDKのFlutter Pluginを利用すれば以下についての対応は不要になります。

Fluter連携の設定

FlutterからSprocketSDKを利用するときは以下の設定が必要になります。

<manifest ... >
<application ... >
...
    <meta-data
        android:name="bz.sprocket.use_flutter_enabled"
        android:value="true" />

</application>

SprocketSDKのライブラリを組み込む

アプリ側のAndroidプロジェクトに libs フォルダにに以下ファイルをコピーし、buid.gradleを設定してライブラリを参照できるようにします。

  • sprocketsdk-api.aar
  • sprocketsdk-core.aar
  • sprocketsdk-ktx.aar
dependencies {
    ...
    implementation fileTree(dir: 'libs', include: ['*.jar', '*.aar'])
}

MainActivityの設定

アプリ側のAndroidプロジェクトにあるMainActivityクラスが継承するクラスをFlutterFragmentActivityにする必要があります。これはSDKで表示するポップアップがFragmentで実装しているためになります。

class MainActivity: FlutterFragmentActivity()

Themeの設定

アプリ側のAndroidプロジェクトにあるThemeを変更する必要があります。ここでの設定がポップアップの表示に影響します。

<manifest xmlns:android="http://schemas.android.com/apk/res/android"  
   xmlns:tools="http://schemas.android.com/tools">  
 
   <application  
       ...
       android:theme="@style/Theme.AppCompat.Light"
       ...

PageTagの設定

アプリ内で各画面を表示したときと閉じるときには以下のコードの呼び出しが必要になります。ここでは現在表示中のPageTagをサーバへ送信しています。
各画面でenterとexitを呼び出す時の引数は同じ値を使用してください。

// 画面ごとにpageTagを定義する
val pageTag = "<pageTag>"

// 画面を表示したとき（SprocketSDKではResumeイベントで呼び出している）
SpSdk.instance.enter(pageTag)

// 画面を閉じるとき（SprocketSDKではPauseイベントで呼び出している）
SpSdk.instance.exit(pageTag)

画面遷移の実装（option）

deepLinkで画面遷移を実現できない場合は、アプリ内で任意の画面に遷移するように実装することができます。

val listener = object : ScreenChangeListener {
    override fun onScreenChange(deepLink: String) {
        ...
        任意の画面に画面遷移する処理を追加
    }
}

// リスナーを登録
SpSdk.instance.addScreenChangeListener(listener)

// リスナーを削除
SpSdk.instance.removeScreenChangeListener(listener)

Updated 9 months ago