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に設定します。 setCustomerUserCodesuspend 関数です。

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.

All modules:

Link copied to clipboard
Link copied to clipboard
Link copied to clipboard