API: Etc

ShopLive.mute

Mute the player

fun mute()

ShopLive.unmute

Unmute the player

fun unmute()

ShopLiveCampaigns.getCampaigns

Retrieves the list of campaigns (broadcasts) that belong to the accessKey, together with the current status of each campaign. Set the accessKey with ShopLive.setAccessKey(accessKey) before calling. Available in Android SDK 1.8.14 and later.

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()
}

Note

• Either onData or onError is called exactly once, on the main thread. An empty result is not an error; onData is called with an empty list.

• Call cancel() on the returned ShopLiveCancellable to cancel a request in progress. After cancelling, no callback is invoked. The SDK does not take a Context or Lifecycle, so cancel the request yourself when leaving the screen (onDestroy).

• In Kotlin, when omitting request, pass the listener as a named argument: getCampaigns(listener = ...). In Java, call getCampaigns(listener).

• ShopLiveCampaigns lives in cloud.shoplive:shoplive-sdk-core; the request/response models and the listener live in cloud.shoplive:shoplive-common. Declare both artifacts and shoplive-network as dependencies.

• Every String field may be an empty string (""), which means "no value". Check with isNullOrBlank() before use. Boolean fields are false when the server omits them.

ShopLiveCampaignListRequest

Query conditions. Every parameter is optional; passing ShopLiveCampaignListRequest() with no arguments fetches all statuses with the server defaults. Conditions without a value are not added to the query.

ShopLiveCampaignListResponse

The query result.

ShopLiveCampaign

Information about a single campaign. All timestamps are epoch millis.

ShopLiveCampaignLifecycle

The status of the campaign and the timestamps of its status transitions.

ShopLiveCampaignStatus

Campaign status values. A sealed class; rawValue returns the raw server value. An undefined value is delivered as Unknown. In Java, compare with instanceof and refer to single statuses such as ShopLiveCampaignStatus.OnAir.INSTANCE.

ShopLiveCampaignMetrics

Viewing metrics. Provided only in the OnAir / Closed statuses.

Error handling

On failure a ShopLiveCommonError is delivered to onError. Determine the cause from code. For server and HTTP errors, message is replaced with the fixed text Failed to fetch campaign list. Refer to the error code. (the server message is not exposed); SDK-internal errors (9000, 9900, 9901, 10000) carry their own SDK message. Server codes can be compared with the ShopLiveCampaignErrorCode constants; see the Error codes document for the full list.

Sample code (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() {

    // The request in progress. Cancelled when the screen is destroyed.
    private var pending: ShopLiveCancellable? = null

    private val listener = object : ShopLiveCampaignListListener {
        override fun onData(response: ShopLiveCampaignListResponse) {
            pending = null
            // An empty list is not an error. It means no campaign matched the conditions.
            response.campaigns.forEach { campaign ->
                val label = when (val status = campaign.lifecycle.status) {
                    ShopLiveCampaignStatus.Reserved -> "Reserved"
                    ShopLiveCampaignStatus.Ready -> if (campaign.lifecycle.rehearsal) "Rehearsal" else "Preparing"
                    ShopLiveCampaignStatus.OnAir -> if (campaign.lifecycle.closingAt == null) "On air" else "Closing"
                    ShopLiveCampaignStatus.Closed -> "Closed"
                    is ShopLiveCampaignStatus.Unknown -> "Unknown status (${status.raw})"
                }
                // String fields may be an empty string (""), so check with isNullOrBlank().
                val title = campaign.title?.takeIf { it.isNotBlank() } ?: "(no title)"
                Log.d("Campaign", "$label ${campaign.campaignKey} $title")
            }
            if (response.hasMore) {
                // Increase page by 1 and fetch the next page.
            }
        }

        override fun onError(error: ShopLiveCommonError) {
            pending = null
            // Determine the cause from code. Do not branch on message.
            Log.e("Campaign", "getCampaigns failed: code=${error.code} message=${error.message}")
        }
    }

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        // Set the accessKey (once per app launch)
        ShopLive.setAccessKey("{accessKey}")

        // Fetch up to 20 on-air and preparing campaigns, newest first
        pending?.cancel()
        pending = ShopLiveCampaigns.getCampaigns(
            request = ShopLiveCampaignListRequest(
                page = 1,
                size = 20,
                statuses = listOf(ShopLiveCampaignFilterStatus.ONAIR, ShopLiveCampaignFilterStatus.READY),
                order = ShopLiveCampaignOrder.DESCENDING,
            ),
            listener = listener,
        )

        // When omitting request, pass the listener as a named argument.
        // ShopLiveCampaigns.getCampaigns(listener = listener)
    }

    override fun onDestroy() {
        // Cancel the request when leaving the screen. No callback is invoked afterwards.
        pending?.cancel()
        pending = null
        super.onDestroy()
    }
}

Sample code (Java)

// Java — when omitting request, call 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();
                    // In Java, compare with instanceof and refer to single statuses via 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) {
                    // The accessKey does not exist
                }
            }
        });

// When leaving the screen
pending.cancel();