API: Etc

ShopLive.mute

プレイヤーをミュートします。

fun mute()

ShopLive.unmute

プレイヤーのミュートを解除します。

fun unmute()

ShopLiveCampaigns.getCampaigns

accessKey に属するキャンペーン(配信)の一覧と、各キャンペーンの現在の状態を取得します。呼び出す前に ShopLive.setAccessKey(accessKey) で accessKey を設定してください。Android SDK 1.8.14 以降で利用できます。

class ShopLiveCampaigns {
    companion object {
        @JvmStatic
        @JvmOverloads
        fun getCampaigns(
            request: ShopLiveCampaignListRequest = ShopLiveCampaignListRequest(),
            listener: ShopLiveCampaignListListener,
        ): ShopLiveCancellable
    }
}

interface ShopLiveCampaignListListener {
    fun onData(response: ShopLiveCampaignListResponse)
    fun onError(error: ShopLiveCommonError)
}

interface ShopLiveCancellable {
    fun cancel()
}

注意

• 結果は onData / onError のどちらかがちょうど 1 回、メインスレッドで呼び出されます。結果が 0 件でもエラーではなく、空のリストで onData が呼び出されます。

• 戻り値 ShopLiveCancellable の cancel() で進行中のリクエストをキャンセルできます。キャンセル後はどのコールバックも呼び出されません。SDK は Context・Lifecycle を受け取らないため、画面を離れるとき(onDestroy)にアプリ側でキャンセルしてください。

• Kotlin で request を省略する場合は getCampaigns(listener = ...) のように名前付き引数で渡します。Java では getCampaigns(listener) で呼び出せます。

• ShopLiveCampaigns は cloud.shoplive:shoplive-sdk-core に、リクエスト・レスポンスのモデルとリスナーは cloud.shoplive:shoplive-common にあります。両方のアーティファクトと shoplive-network を依存関係として宣言してください。

• すべての String フィールドは空文字列("")になり得ます。これは「値なし」を意味するため、使用前に isNullOrBlank() で確認してください。Boolean フィールドはサーバーが値を返さない場合 false です。

ShopLiveCampaignListRequest

取得条件です。すべてのパラメータは任意(オプション)で、引数なしの ShopLiveCampaignListRequest() を渡すとサーバーのデフォルト値で全状態を取得します。値を指定しない条件はクエリに付与されません。

ShopLiveCampaignListResponse

取得結果です。

ShopLiveCampaign

キャンペーン 1 件の情報です。時刻はすべて epoch millis です。

ShopLiveCampaignLifecycle

キャンペーンの状態と、状態遷移の時刻です。

ShopLiveCampaignStatus

キャンペーンの状態値です。sealed class で、rawValue からサーバーの元の値を取得できます。未定義の値は Unknown として渡されます。Java では instanceof で比較し、単一の状態は ShopLiveCampaignStatus.OnAir.INSTANCE のように参照します。

ShopLiveCampaignMetrics

視聴指標です。OnAir / Closed の状態でのみ提供されます。

エラー処理

失敗時は onError に ShopLiveCommonError が渡されます。原因は code で判別してください。サーバーエラー・HTTP エラーの message は固定文言 Failed to fetch campaign list. Refer to the error code. に置き換えられ(サーバーの原文は公開されません)、SDK 内部エラー(9000・9900・9901・10000)は各エラーの SDK 文言がそのまま入ります。サーバーが返したコードは ShopLiveCampaignErrorCode の定数と比較できます。コードの一覧は Error codes ドキュメントを参照してください。

サンプルコード (Kotlin)

import cloud.shoplive.sdk.ShopLive
import cloud.shoplive.sdk.ShopLiveCampaigns
import cloud.shoplive.sdk.common.ShopLiveCancellable
import cloud.shoplive.sdk.common.ShopLiveCommonError
import cloud.shoplive.sdk.common.campaign.ShopLiveCampaignFilterStatus
import cloud.shoplive.sdk.common.campaign.ShopLiveCampaignListListener
import cloud.shoplive.sdk.common.campaign.ShopLiveCampaignListRequest
import cloud.shoplive.sdk.common.campaign.ShopLiveCampaignListResponse
import cloud.shoplive.sdk.common.campaign.ShopLiveCampaignOrder
import cloud.shoplive.sdk.common.campaign.ShopLiveCampaignStatus

class CampaignListActivity : AppCompatActivity() {

    // 進行中のリクエスト。画面を離れるときにキャンセルします。
    private var pending: ShopLiveCancellable? = null

    private val listener = object : ShopLiveCampaignListListener {
        override fun onData(response: ShopLiveCampaignListResponse) {
            pending = null
            // 0 件はエラーではありません。条件に合う配信がないことを意味します。
            response.campaigns.forEach { campaign ->
                val label = when (val status = campaign.lifecycle.status) {
                    ShopLiveCampaignStatus.Reserved -> "予約"
                    ShopLiveCampaignStatus.Ready -> if (campaign.lifecycle.rehearsal) "リハーサル中" else "準備中"
                    ShopLiveCampaignStatus.OnAir -> if (campaign.lifecycle.closingAt == null) "配信中" else "終了処理中"
                    ShopLiveCampaignStatus.Closed -> "終了"
                    is ShopLiveCampaignStatus.Unknown -> "不明な状態(${status.raw})"
                }
                // String フィールドは空文字列("")になり得るため isNullOrBlank() で確認します。
                val title = campaign.title?.takeIf { it.isNotBlank() } ?: "(タイトルなし)"
                Log.d("Campaign", "$label ${campaign.campaignKey} $title")
            }
            if (response.hasMore) {
                // page を 1 増やして次のページを取得します。
            }
        }

        override fun onError(error: ShopLiveCommonError) {
            pending = null
            // 原因は code で判別します。message で分岐しないでください。
            Log.e("Campaign", "getCampaigns failed: code=${error.code} message=${error.message}")
        }
    }

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        // accessKey の設定 (アプリで最初に 1 回)
        ShopLive.setAccessKey("{accessKey}")

        // 配信中・準備中のキャンペーンを新しい順に 20 件取得
        pending?.cancel()
        pending = ShopLiveCampaigns.getCampaigns(
            request = ShopLiveCampaignListRequest(
                page = 1,
                size = 20,
                statuses = listOf(ShopLiveCampaignFilterStatus.ONAIR, ShopLiveCampaignFilterStatus.READY),
                order = ShopLiveCampaignOrder.DESCENDING,
            ),
            listener = listener,
        )

        // request を省略する場合は listener に名前を付けて渡します。
        // ShopLiveCampaigns.getCampaigns(listener = listener)
    }

    override fun onDestroy() {
        // 画面を離れるときにリクエストをキャンセルします。以降、コールバックは呼び出されません。
        pending?.cancel()
        pending = null
        super.onDestroy()
    }
}

サンプルコード (Java)

// Java — request を省略する場合は getCampaigns(listener) で呼び出せます。
ShopLiveCancellable pending = ShopLiveCampaigns.getCampaigns(
        new ShopLiveCampaignListRequest(1, 20,
                Collections.singletonList(ShopLiveCampaignFilterStatus.ONAIR),
                ShopLiveCampaignOrder.DESCENDING),
        new ShopLiveCampaignListListener() {
            @Override
            public void onData(@NonNull ShopLiveCampaignListResponse response) {
                for (ShopLiveCampaign campaign : response.getCampaigns()) {
                    ShopLiveCampaignStatus status = campaign.getLifecycle().getStatus();
                    // Java では instanceof で比較し、単一の状態は INSTANCE で参照します。
                    if (status == ShopLiveCampaignStatus.OnAir.INSTANCE) {
                        Log.d("Campaign", "on air: " + campaign.getCampaignKey());
                    } else if (status instanceof ShopLiveCampaignStatus.Unknown) {
                        Log.d("Campaign", "unknown: " + status.getRawValue());
                    }
                }
            }

            @Override
            public void onError(@NonNull ShopLiveCommonError error) {
                if (error.getCode() == ShopLiveCampaignErrorCode.SERVICE_NOT_EXIST) {
                    // 存在しない accessKey
                }
            }
        });

// 画面を離れるとき
pending.cancel();