staffstart-android-sdk
STAFF START の Android SDK
構成
staffstart-core, staffstart-app,staffstart-trackingの3つ それぞれの役割は下記
| staffstart-core | staffstart-app | staffstart-tracking | |
|---|---|---|---|
| Entityの保持、公開, App、Core共通で利用されるような共通処理などを配置 | ViewやAPIエンドポイントをcallしてレスポンスを受け取る | 計測タグの送信 | |
| dependencies | staffstart-core | staffstart-core | |
| architecture | domain / framework | domain / infrastructure / framework / view / viewmodel (MVVM + Jetpack Compose) | domain / infrastructure / framework |
概要
このSDKは、STAFF STARTのデータをAndroidアプリに簡単かつ効果的に統合し、活用できるよう設計されています。アプリ内でのデータ活用を通じて、よりスムーズで高度なユーザー体験を提供します。
特徴
このSDKは、以下の3つのフレームワークで構成されており、それぞれ異なる役割を担っています:
StaffStart_Core
アプリの初期化処理を担当します。SDKを利用する際の基本的な設定や準備を行います。
StaffStart_App
STAFF STARTのAPIと連携し、データの取得や操作を行います。データ活用の中心的な役割を果たします。
StaffStart_Tracking
ユーザーアクションやイベントの計測を行い、データ分析やパフォーマンス最適化をサポートします。
これらのフレームワークを組み合わせることで、柔軟かつ効率的にSTAFF STARTのデータを活用することができます。
必須要件
| 項目 | バージョン |
|---|---|
| minSdk | 28 |
| compileSdk | 35 |
| Kotlin | 2.1.0 以上 |
動作確認済み環境
| ライブラリ | バージョン |
|---|---|
| Jetpack Navigation 3 | 1.0.0 |
| Jetpack Navigation Compose | 2.7.6 |
| Jetpack Compose BOM | 2025.01.00 |
注意: 上記以外の環境での動作は確認していないため、サポート対象外となります。
クイックスタート
開発環境のセットアップ
下記コマンドを叩いて、SDKをビルドしてAARファイルを生成します。 AARファイルは、example/libs にコピーされます。
sh build_and_copy_aars.sh
Exampleアプリの実行
build variantをreleaseに変更することで、リリース用のAARをExampleから確認することができます。
StaffStart SDKの設定と初期化
StaffStart SDKをアプリに統合する際の設定と初期化方法について説明します。本SDKのサンプルアプリのMainActivityを例に具体的な手順を示します。
依存関係の追加
build.gradleファイルに以下の依存関係を追加します。
dependencies {
implementation "com.example.staffstart:staffstart-sdk:1.6.8"
}
Kotlin DSLの場合は以下のように記述します。
dependencies {
implementation("com.example.staffstart:staffstart-sdk:1.6.8")
}
StaffStart SDKの設定と初期化
SDKを利用するには、初期設定が必要です。StaffStartConfigurationを使用して設定情報を提供します。
StaffStart.Core.initialize / StaffStart.tracking.initialize はいずれも suspend 関数のため、コルーチンから呼び出してください。 また StaffStart.tracking は staffstart-tracking が提供する拡張プロパティのため、import が必要です。
import com.vanish.standard.staffstart.core.domain.enum.ContractType
import com.vanish.standard.staffstart.core.framework.config.StaffStart
import com.vanish.standard.staffstart.core.framework.config.StaffStartConfiguration
import com.vanish.standard.staffstart.tracking.framework.config.tracking // StaffStart.tracking を使うために必要
private fun initializeStaffStartSDK() {
val staffStartConfiguration = StaffStartConfiguration(
merchantId = "YOUR_MERCHANT_ID", // マーチャントIDを設定してください
api = "https://test.staff-start.com", // APIのベースURL
trackingApi = "https://test-analytics.staff-start.com", // トラッキングAPIのURL
contractType = ContractType.BRAND // 契約種別(省略可。デフォルトは BRAND)
)
lifecycleScope.launch {
// Core機能(staffstart-core)の初期化
StaffStart.Core.initialize(staffStartConfiguration)
// 計測機能(staffstart-tracking)の初期化
StaffStart.tracking.initialize(applicationContext)
}
}
contractType には以下のいずれかを指定します。
| 値 | 説明 |
|---|---|
ContractType.BRAND |
ブランド(既定値) |
ContractType.MULTI_BRAND |
マルチブランド |
ContractType.MALL |
モール |
お気に入り取得APIなどを使用する場合、顧客IDの保持が必要です。顧客IDは、アプリ内で一意のIDを生成し、SDKに設定します。 setCustomerUserCode も suspend 関数です。
lifecycleScope.launch {
StaffStart.Core.setCustomerUserCode("someUniqueId")
}
また、ログアウト時には、顧客IDをnullに設定します。
lifecycleScope.launch {
StaffStart.Core.setCustomerUserCode(null)
}
リソースの解放
アプリの終了時にリソースを解放します。onDestroyでStaffStart SDKのリソースを解放してください
override fun onDestroy() {
super.onDestroy()
StaffStart.Core.close()
}
詳細については、APIリファレンス をご参照ください。初期設定に必要な詳細な手順やコードサンプルが記載されています。
UI表示方法
共通事項
すべての画面 / ブロックコンポーネントは、以下の引数を共通で受け取ります。
| 引数 | 型 | 既定値 | 説明 |
|---|---|---|---|
useDarkTheme |
Boolean |
false |
ダークテーマで描画するかどうか。端末設定に追従させる場合は isSystemInDarkTheme() を渡します |
onFavoriteAttemptWithoutLogin |
() -> Unit |
{} |
未ログイン状態でお気に入りボタンがタップされた際に呼ばれます(引数はありません) |
UI設定方法
StaffStartUIの初期設定を行います。StaffStartUIConfigurationを使用して設定情報を提供します。 StaffStartUI.Configureを使用して、コールバックを設定します。
StaffStartUI.Configure(
StaffStartUIConfiguration(
onTapProductItem = { productCode ->
// 商品タップ時の処理
},
onShowCoordinateDetail = { snapPlayId ->
// コーディネート詳細が表示された時の処理
}
)
)
画面(Screen)
コーディネート一覧 StaffStartSnapPlayListScreen
コーディネート一覧レイアウトを表示するには、StaffStartSnapPlayListScreenを使用します。 絞り込み条件は SnapPlaySearchConditionRouteParams で指定します(すべてのプロパティにデフォルト値があるため、絞り込みが不要な場合は SnapPlaySearchConditionRouteParams() を渡してください)。
StaffStartSnapPlayListScreen(
snapPlaySearchConditionRouteParams = SnapPlaySearchConditionRouteParams(
labelId = 3,
order = Order.NEW_ARRIVAL
),
onTapSnapPlay = { snapPlayId ->
// SnapPlayタップ時の処理
},
onFavoriteAttemptWithoutLogin = {
// ログインを促す処理
}
)
コーディネート詳細 StaffStartSnapPlayDetailScreen
コーディネート詳細レイアウトを表示するには、StaffStartSnapPlayDetailScreenを使用します。
StaffStartSnapPlayDetailScreen(
snapPlayId = "1",
onTapStaff = { staffId ->
// スタッフタップ時の処理
// staffId: タップされたスタッフのID
},
onTapSnapPlayFilter = { snapPlayFilterParams ->
// SnapPlay絞り込みボタンタップ時の処理
// snapPlayFilterParams: SnapPlayFilterParams
},
onTapSnapPlay = { snapPlayId ->
// SnapPlayタップ時の処理
},
onTapProductItem = { productCode ->
// 商品タップ時の処理
},
onTapSnapPlayNotFoundBack = {
// SnapPlayが見つからない場合の戻るボタンタップ時の処理
},
onFavoriteAttemptWithoutLogin = {
// ログインを促す処理
}
)
スタッフ一覧 StaffStartStaffListScreen
スタッフ一覧レイアウトを表示するには、StaffStartStaffListScreenを使用します。 絞り込み条件は StaffSearchConditionRouteParams で指定します(絞り込みが不要な場合は StaffSearchConditionRouteParams() を渡してください)。
StaffStartStaffListScreen(
staffSearchConditionRouteParams = StaffSearchConditionRouteParams(
labelId = 3,
order = Order.NEW_ARRIVAL
),
onTapStaff = { staffId ->
// スタッフタップ時の処理
},
onFavoriteAttemptWithoutLogin = {
// ログインを促す処理
}
)
スタッフ詳細 StaffStartStaffDetailScreen
スタッフ詳細レイアウトを表示するには、StaffStartStaffDetailScreenを使用します。
StaffStartStaffDetailScreen(
staffId = "1",
onTapSnapPlay = { snapPlayId ->
// SnapPlayタップ時の処理
},
onTapSnapPlayFilter = { snapPlayFilterParams ->
// SnapPlay絞り込みボタンタップ時の処理
},
onFavoriteAttemptWithoutLogin = {
// ログインを促す処理
}
)
お気に入りコーディネート一覧 StaffStartFavoriteSnapPlayListScreen
お気に入り登録済みのコーディネート一覧を表示するには、StaffStartFavoriteSnapPlayListScreenを使用します。 表示には StaffStart.Core.setCustomerUserCode() による顧客IDの設定が必要です。
StaffStartFavoriteSnapPlayListScreen(
onTapSnapPlay = { snapPlayId ->
// SnapPlayタップ時の処理
},
onFavoriteAttemptWithoutLogin = {
// ログインを促す処理
}
)
SDK内蔵ナビゲーション
個別の画面を自前で繋ぎ込む代わりに、SDKが持つ NavHost をそのまま利用することもできます。 Scene.SNAP_PLAY / Scene.STAFF の2つのシーンがあり、それぞれ StaffStartUI.SnapPlayNavigation / StaffStartUI.StaffNavigation で表示します。
StaffStartUI.SnapPlayNavigation(
useDarkTheme = isSystemInDarkTheme(),
onFavoriteAttemptWithoutLogin = {
// ログインを促す処理
}
)
アプリ側から SDK の画面遷移をトリガーする場合は、StaffStartUI.getNavController(scene) で NavHostController を取得し、遷移用のヘルパーを呼び出します。
val navController = StaffStartUI.getNavController(Scene.SNAP_PLAY)
StaffStartUI.navigateToSnapPlayDetail(navController, snapPlayId = "1")
StaffStartUI.navigateToSnapPlayList(navController, SnapPlaySearchConditionRouteParams(labelId = 3))
StaffStartUI.navigateToStaffDetail(navController, staffId = "1")
StaffStartUI.navigateToStaffList(navController, StaffSearchConditionRouteParams(labelId = 3))
ブロック(任意のページへの埋め込み)
商品別コーディネート一覧 StaffStartBaseProductSnapPlaysBlock
任意のページのパーツとしてコーディネートの一覧を表示する際にはStaffStartBaseProductSnapPlaysBlockを使用します。 セクション見出しは sectionTitle(既定値: "この商品を使ったコーディネート")で変更できます。
StaffStartBaseProductSnapPlaysBlock(
baseProductCode = "baseProductCode",
onTapSnapPlayDetail = { snapPlayId ->
// SnapPlayタップ時の処理
},
onTapReadMore = { baseProductCode ->
// もっと見るボタンタップ時の処理
},
onFavoriteAttemptWithoutLogin = {
// ログインを促す処理
}
)
ブランド別コーディネート一覧 StaffStartBrandSnapPlaysBlock
ブランド別コーディネート一覧を表示する際にはStaffStartBrandSnapPlaysBlockを使用します。
StaffStartBrandSnapPlaysBlock(
conditions = BrandSnapPlaysBlockCondition(
labelId = labelId,
coordinateGenre = CoordinateGenre.MALE,
tags = setOf("テストタグ2", "タグランキングテスト"),
order = Order.POPULARITY,
),
onTapSnapPlay = { snapPlayId ->
// SnapPlayタップ時の処理
},
onFavoriteAttemptWithoutLogin = {
// ログインを促す処理
}
)
ブランド別スタッフ一覧 StaffStartBrandStaffsBlock
ブランド別スタッフ一覧を表示する際にはStaffStartBrandStaffsBlockを使用します。
StaffStartBrandStaffsBlock(
conditions = BrandStaffsBlockConditions(
labelId = 3,
order = Order.NEW_ARRIVAL
),
onTapStaff = { staffId ->
// スタッフタップ時の処理
},
onFavoriteAttemptWithoutLogin = {
// ログインを促す処理
}
)
詳細については、APIリファレンス をご参照ください。初期設定に必要な詳細な手順やコードサンプルが記載されています。
計測タグ設定方法
計測は StaffStartTracking から行います。事前に StaffStart.tracking.initialize(applicationContext) が完了している必要があります。 いずれのメソッドも suspend 関数のため、コルーチンから呼び出してください。
| メソッド | 用途 | パラメータ |
|---|---|---|
StaffStartTracking.trackPageView(params) |
ページビュー計測 | PageViewParams |
StaffStartTracking.trackAddToCart(params) |
カート追加計測 | AddToCartParams |
StaffStartTracking.trackPurchase(params) |
購入計測 | PurchaseParams |
import com.vanish.standard.staffstart.core.domain.enum.ContentType
import com.vanish.standard.staffstart.tracking.StaffStartTracking
import com.vanish.standard.staffstart.tracking.domain.model.AddToCartParams
import com.vanish.standard.staffstart.tracking.domain.model.PageViewParams
import com.vanish.standard.staffstart.tracking.domain.model.ProductInfo
import com.vanish.standard.staffstart.tracking.domain.model.PurchaseParams
lifecycleScope.launch {
// ページビュー
StaffStartTracking.trackPageView(
PageViewParams(
contentId = 12345,
userId = "User123", // 未ログイン時は null
contentType = ContentType.COORDINATE
)
)
// カート追加
StaffStartTracking.trackAddToCart(
AddToCartParams(
sku = "ABC123",
count = 1
)
)
// 購入
StaffStartTracking.trackPurchase(
PurchaseParams(
userId = "User123", // 未ログイン時は null
orderId = "ORDER-0001",
productInfo = listOf(
ProductInfo(sku = "ABC123", price = 1980, count = 1)
)
)
)
}
詳細について、APIリファレンス をご参照ください。
SDK開発者向け
ktlintの適用
gitのコミット時にktlintを適用するために、pre-commitを設定しています。
設定するには以下のコマンドを実行してください。
chmod +x .githooks/pre-commit
git config core.hooksPath .githooks
Exampleアプリの開発
開発時にSDKのDEBUGを行いたい場合、toggle_example.shを実行してSDKのサブプロジェクトにしてください
ドキュメント更新
ドキュメントは、Dokka で生成されています。ドキュメントを更新するには、以下のコマンドを実行してください。
./gradlew dokkaHtmlMultiModule
License
This project is licensed under the Apache License 2.0 - see the LICENSE file for details.