API: Etc

mute

Mute the currently playing video.

func mute()

Sample code

ShopLive.mute()

unmute

Unmute the currently playing video.

func unmute()

Sample code

ShopLive.unmute()

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.configure(with:) before calling. Available in iOS SDK 1.8.15 and later.

extension ShopLive.API {

    // completion
    @discardableResult
    static func getCampaigns(_ request: ShopLiveCampaignListRequest = ShopLiveCampaignListRequest(),
                             completion: @escaping (Result<ShopLiveCampaignListResponse, ShopLiveCommonError>) -> Void) -> ShopLiveCancellable

    // async/await (iOS 13+)
    static func getCampaigns(_ request: ShopLiveCampaignListRequest = ShopLiveCampaignListRequest()) async throws -> ShopLiveCampaignListResponse
}

Note

• The completion handler is called on the main thread.

• Call cancel() on the returned ShopLiveCancellable to cancel a request in progress. With the async version, cancelling the Task also cancels the request.

• The request and response types are defined in the ShopliveSDKCommon module. Add import ShopliveSDKCommon when you refer to the type names directly in code.

ShopLiveCampaignListRequest

Query conditions. Every parameter is optional; passing ShopLiveCampaignListRequest() with no arguments fetches all statuses with the server defaults.

ShopLiveCampaignListResponse

The query result.

ShopLiveCampaign

Information about a single campaign.

ShopLiveCampaign.Lifecycle

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

ShopLiveCampaign.Status

Campaign status values. Server values are mapped as-is; an undefined value is delivered as .unknown.

ShopLiveCampaign.Metrics

Viewing metrics. Provided only in the .onair / .closed statuses.

Error handling

On failure a ShopLiveCommonError is delivered. codes holds the error code, and message is always the fixed text Failed to fetch campaign list. Refer to the error code. Determine the cause from codes. Error codes returned by the server are passed through as-is; see the Error codes document for the full list.

Sample code

import ShopLiveSDK
import ShopliveSDKCommon

// Set the accessKey (once per app launch)
ShopLive.configure(with: "{accessKey}")

// Fetch up to 20 on-air and preparing campaigns, newest first
let request = ShopLiveCampaignListRequest(page: 1,
                                          size: 20,
                                          statuses: [.onair, .ready],
                                          order: .descending)

let cancellable = ShopLive.API.getCampaigns(request) { result in
    switch result {
    case let .success(response):
        for campaign in response.campaigns {
            switch campaign.lifecycle.status {
            case .reserved:
                print("Reserved", campaign.title ?? "")
            case .ready:
                print(campaign.lifecycle.rehearsal ? "Rehearsal" : "Preparing", campaign.title ?? "")
            case .onair:
                print(campaign.lifecycle.closingAt == nil ? "On air" : "Closing", campaign.title ?? "")
            case .closed:
                print("Closed", campaign.title ?? "")
            case let .unknown(raw):
                print("Unknown status", raw)
            }
        }
        if response.hasMore {
            // Increase page by 1 and fetch the next page.
        }
    case let .failure(error):
        print("getCampaigns failed:", error.codes, error.message ?? "")
    }
}

// Cancel the request when the result is no longer needed (e.g. the screen is dismissed).
// cancellable.cancel()

Sample code (async/await)

// iOS 13+ — cancelling the Task also cancels the request in progress.
Task {
    do {
        let response = try await ShopLive.API.getCampaigns(ShopLiveCampaignListRequest(statuses: [.onair]))
        let onair = response.campaigns.filter { $0.lifecycle.closingAt == nil }
        if let campaign = onair.first {
            ShopLive.play(data: ShopLivePlayerData(campaignKey: campaign.campaignKey))
        }
    } catch let error as ShopLiveCommonError {
        print("getCampaigns failed:", error.codes)
    } catch {
        // Task cancellation (CancellationError), etc.
    }
}