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 중 정확히 한 번, 메인 스레드에서 호출됩니다. 조회 결과가 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

조회 조건입니다. 모든 파라미터는 선택(optional)이며, 인자 없이 ShopLiveCampaignListRequest() 를 넘기면 서버 기본값으로 전체 상태를 조회합니다. 값을 주지 않은 조건은 쿼리에 붙이지 않습니다.

ShopLiveCampaignListResponse

조회 결과입니다.

ShopLiveCampaign

캠페인 한 건의 정보입니다. 시각 값은 모두 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 문서를 참고하세요.

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

    // 진행 중인 요청. 화면을 벗어날 때 취소합니다.
    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()
    }
}

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