Event Handler

Shoplive Playerで発生したユーザーUIイベントや状態変更などの通知をクライアントからハンドラ(delegate)関数を介して受け取り、必要な処理をします。

delegate

Shoplive iOS SDKのハンドライベントを受け取る関数を宣言し、Shoplive iOS SDKとイベントを接続する propertyです。

@objc var delegate: ShopLiveSDKDelegate? { get set }

@objc public protocol ShopLiveSDKDelegate: AnyObject {
    @objc func handleNavigation(with url: URL)
    @objc func handleChangeCampaignStatus(status: String)
    @objc optional func handleChangedPlayerStatus(status: String)
    @objc func handleCampaignInfo(campaignInfo: [String : Any])

    @objc func onSetUserName(_ payload: [String : Any])

    @objc func handleCommand(_ command: String, with payload: Any?)
    @objc func handleReceivedCommand(_ command: String, data: [String: Any]?)

    @objc func handleError(code: String, message: String)

    @objc optional func handleDownloadCoupon(with couponId: String, result: @escaping (ShopLiveCouponResult) -> Void)
    @objc optional func handleCustomAction(with id: String, type: String, payload: Any?, result: @escaping (ShopLiveCustomActionResult) -> Void)
    @objc optional func playerPanGesture(state: UIGestureRecognizer.State, position: CGPoint)
    @objc optional func log(name: String, feature: ShopLiveLog.Feature, campaign: String, payload: [String: Any])

}

サンプルコード

class MainViewController: UIViewController {
    ...
    override func viewDidLoad() {
        super.viewDidLoad()

        // delegateと現在のクラスを連結します。
        ShopLive.delegate = self

    }
    ...
}

// delegateを接続するクラスはShopLiveSDKDelegate Protocolを実装します。
extension MainViewController: ShopLiveSDKDelegate {
    func handleNavigation(with url: URL) {
        print("handleNavigation \(url)")
    }
    ...
}

handleNavigation

Shopliveで商品、バナーなどを選択(タップ)したとき、選択した商品またはバナー情報を伝達します。

handleNavigation(with url: URL)

サンプルコード

extension MainViewController: ShopLiveSDKDelegate {
    func handleNavigation(with url: URL) {
        print("handleNavigation \(url)")

        UIApplication.shared.open(url, options: [:], completionHandler: nil)
    }
    ...
}

handleChangeCampaignStatus

放送状態が変更された場合、変更された放送状態を伝えます。

@objc func handleChangeCampaignStatus(status: String)

サンプルコード

extension MainViewController: ShopLiveSDKDelegate {
    func handleChangeCampaignStatus(status: String) {
        print("handleChangeCampaignStatus \(status)")

        switch status {
            case "READY", "ONAIR":
                break
            case "CLOSED":
                print("ended campaign")
                break
        }
    }
    ...
}

handleChangedPlayerStatus

Shoplive Playerのステータスを受け取ります。

handleChangedPlayerStatus(status: String)

サンプルコード

extension MainViewController: ShopLiveSDKDelegate {
    func handleChangedPlayerStatus(status: String) {
        print("handleChangedPlayerStatus \(status)")

        switch status {
            case "CREATED":
                break
            case "DESTROYED":
                break
        }
    }
    ...
}

handleCampaignInfo

現在の放送に関する情報をお伝えします。

handleCampaignInfo(campaignInfo: [String : Any])

サンプルコード

extension MainViewController: ShopLiveSDKDelegate {
    func handleCampaignInfo(campaignInfo: [String : Any]) {

        campaignInfo.forEach { (key, value) in
            print("campaignInfo key: \(key)  value: \(value)")
        }

    }
    ...
}

onSetUserName

ユーザー名が変更されたときに呼び出されます。

onSetUserName(_ payload: [String : Any])

サンプルコード

extension MainViewController: ShopLiveSDKDelegate {
    func onSetUserName(_ payload: [String : Any]) {
        payload.forEach { (key, value) in
            print("onSetUserName key: \(key) value: \(value)")
        }
    }
    ...
}

Shoplive Player ステータスの変更

Shoplive Player 状態が変更されたときに command を渡します。

ShopLiveViewTrackEvent

@objc public enum ShopLiveViewTrackEvent : Int, CaseIterable {
    case viewWillDisAppear
    case viewDidDisAppear
    case pipWillAppear
    case pipDidAppear
    case fullScreenWillAppear
    case fullScreenDidAppear
    
    public var name : String {
        switch self {
        case .viewWillDisAppear:
            return "viewWillDisAppear"
        case .viewDidDisAppear:
            return "viewDidDisAppear"
        case .pipWillAppear:
            return "pipWillAppear"
        case .pipDidAppear:
            return "pipDidAppear"
        case .fullScreenWillAppear:
            return "fullScreenWillAppear"
        case .fullScreenDidAppear:
            return "fullScreenDidAppear"
        }
    }
}

payload

変更前にShoplive Playerの状態を payload に渡します。

ShopLiveViewHiddenActionType

Deprecated

payload

変更前にShoplive Playerの状態を payloadに渡します。 

サンプルコード

extension MainViewController: ShopLiveSDKDelegate {
    func handleCommand(_ command: String, with payload: Any?) {
        print("handleCommand: \(command)  payload: \(payload)") 
    }
    ...
}

handleReceivedCommand

Shoplive iOS SDKのWEBから受信した命令情報を渡します。

handleReceivedCommand(_ command: String, with data: [String: Any]?)

サンプルコード

extension MainViewController: ShopLiveSDKDelegate {
    func handleReceivedCommand(_ command: String, data: [String: Any]?) {
        switch command {
        case "LOGIN_REQUIRED":
            let alert = UIAlertController(title: command, message: "alert.login.required.description".localized(), preferredStyle: .alert)
            alert.addAction(.init(title: "alert.msg.ok".localized(), style: .default, handler: { _ in
                /*ログイン
                    1.ログイン画面に移動
                    2.ログインが成功したら、認証ユーザーアカウントを連動してショップライブプレーヤーを再呼び出しします。
                 */ログイン
                ShopLive.startPictureInPicture()
                let login = LoginViewController()
                login.delegate = self
                self.navigationController?.pushViewController(login, animated: true)
            }))
            alert.addAction(.init(title: "alert.msg.no".localized(), style: .default, handler: { _ in
                alert.dismiss(animated: true)
            }))
            ShopLive.viewController?.present(alert, animated: true, completion: nil)
            break
        case "CLICK_PRODUCT_CART":
          break
        default:
            break
        }
      
    }
    ...
}

• 関連ガイド : messageCallback

Change the status of the Shoplive Player

Shoplive Player のステータスが変化すると、ShopLiveViewTrackEvent がコマンドとして渡されます。

ShopLiveViewTrackEvent

@objc public enum ShopLiveViewTrackEvent : Int, CaseIterable {
    case viewWillDisAppear
    case viewDidDisAppear
    case pipWillAppear
    case pipDidAppear
    case fullScreenWillAppear
    case fullScreenDidAppear
    
    public var name : String {
        switch self {
        case .viewWillDisAppear:
            return "viewWillDisAppear"
        case .viewDidDisAppear:
            return "viewDidDisAppear"
        case .pipWillAppear:
            return "pipWillAppear"
        case .pipDidAppear:
            return "pipDidAppear"
        case .fullScreenWillAppear:
            return "fullScreenWillAppear"
        case .fullScreenDidAppear:
            return "fullScreenDidAppear"
        }
    }
}

payload

以前の Shoplive Player のステータスをペイロードとして配信します。

ShopLiveViewHiddenActionType

Deprecated

payload

以前の Shoplive Player のステータスをペイロードとして伝えます。

Sample code

extension MainViewController: ShopLiveSDKDelegate {
    func handleCommand(_ command: String, with payload: Any?) {
        print("handleCommand: \(command)  payload: \(String(describing: payload))") 
    }
    ...
}

Coupon

クーポン処理が完了したときにクーポンが有効かどうかを設定するための状態です。

@objc public enum ShopLiveResultStatus: Int, CaseIterable {
    case SHOW // クーポン再アクティブ化
    case HIDE // クーポン消失
    case KEEP // 状態を維持する

    public var name: String {
        switch self {
        case .SHOW:
            return "SHOW"
        case .HIDE:
            return "HIDE"
        case .KEEP:
            return "KEEP"
        }
    }
}

クーポン処理が完了したときに、通知メッセージがあれば表示されるタイプを設定します。

@objc public enum ShopLiveResultAlertType: Int, CaseIterable {
    case ALERT // アラート
    case TOAST // トースト

    public var name: String {
        switch self {
        case .ALERT:
            return "ALERT"
        case .TOAST:
            return "TOAST"
        }
    }
}

@objc public class ShopLiveCouponResult: NSObject {
    var success: Bool // クーポン処理の成功/失敗の有無
    var coupon: String = "" // クーポン ID
    var message: String? // 通知メッセージ
    var couponStatus: ShopLiveResultStatus // 完了後のクーポンステータス
    var alertType: ShopLiveResultAlertType // 通知メッセージ出力タイプ

    public init(couponId: String, success: Bool, message: String?, status: ShopLiveResultStatus, alertType: ShopLiveResultAlertType) {
        self.coupon = couponId
        self.success = success
        self.message = message
        self.couponStatus = status
        self.alertType = alertType
    }
}

@objc public class ShopLiveCustomActionResult: NSObject {
    var success: Bool // カスタムアクション処理の成功/失敗
    var id: String = "" // カスタムアクションの ID   
    var message: String? // 通知メッセージ
    var couponStatus: ShopLiveResultStatus // 完了後のカスタムアクション状態
    var alertType: ShopLiveResultAlertType // 通知メッセージの出力タイプ

    public init(id: String, success: Bool, message: String?, status: ShopLiveResultStatus, alertType: ShopLiveResultAlertType) {
        self.id = id
        self.success = success
        self.message = message
        self.couponStatus = status
        self.alertType = alertType
    }
}

handleDownloadCoupon

Shopliveでクーポンを選択（タップ）したときにクライアントにクーポン情報を渡します。クライアントのクーポン処理結果を Shoplive iOS SDK に返す result callback を使用して、Shoplive Player でのクーポンステータスを設定します。

handleDownloadCoupon(with couponId: String, result: @escaping (ShopLiveCouponResult) -> Void)

サンプルコード

extension MainViewController: ShopLiveSDKDelegate {
    func handleDownloadCoupon(with couponId: String, result: @escaping (ShopLiveCouponResult) -> Void) {
        print("handleDownloadCoupon: \(couponId)")

        // クーポン処理完了時に呼び出し (処理結果)
        // 成功
        let couponResult = ShopLiveCouponResult(couponId: couponId, success: true, message: "クーポンのダウンロードが成功しました。", status： .SHOW, alertType: .ALERT)
        // 失敗
        let couponResult = ShopLiveCouponResult(couponId: couponId, success: false, message: "クーポンのダウンロードに失敗しました。", status: .HIDE, alertType: .TOAST)
        result(couponResult)
    }
    ...
}

• アプリケーションガイド: クーポンを使う

handleCustomAction

ポップアップでクリックイベントを customで指定し、ポップアップを選択(タップ)した時、ポップアップ情報を伝達します。ポップアップの id, type (COUPON, BANNER, NOTICE), payloadを渡します。

handleCustomAction(with id: String, type: String, payload: Any?, result: @escaping (ShopLiveCustomActionResult) -> Void)

サンプルコード

extension MainViewController: ShopLiveSDKDelegate {
    func handleCustomAction(with id: String, type: String, payload: Any?, result: @escaping (ShopLiveCustomActionResult) -> Void) {
        print("handleCustomAction \(id) \(type) \(payload.debugDescription)")

        // ポップアップ処理が完了すると呼び出される(処理結果)
        // 成功
        let customActionResult = ShopLiveCustomActionResult(id: id, success: true, message: "Coupon download was successful.", status： .SHOW, alertType: .ALERT)

        // 失敗
        let customActionResult = ShopLiveCustomActionResult(id: id, success: false, message: "Coupon download was failed.", status: .HIDE, alertType: .TOAST)

        result(customActionResult)
    }
    ...
}

handleError

放送前または放送中に発生したエラー状況に関するメッセージを配信します。

handleError(code: String, message: String)

サンプルコード

extension MainViewController: ShopLiveSDKDelegate {
    func handleError(code: String, message: String) {
        print("handleError \(code) \(message)")
    }
    ...
}

playerPanGesture

PIPモードでウィンドウ位置を動かすと、ウィンドウの座標とジェスチャーイベントの状態を渡します。

playerPanGesture(state: UIGestureRecognizer.State, position: CGPoint)

サンプルコード

extension MainViewController: ShopLiveSDKDelegate {
	func playerPanGesture(state: UIGestureRecognizer.State, position: CGPoint) {
    	print("gesture state \(state) position \(position)")
	}
  ...
}

log

Shoplive Playerのイベントログを転送します。この情報は、Google Analyticsなどの分析ツールで利用できます。

log(name: String, feature: ShopLiveLog.Feature, campaign: String, payload: [String: Any])

ShopLiveLog

Shoplive Playerのイベントログを転送します。この情報は、Google Analyticsなどの分析ツールで利用できます。

@objc public class ShopLiveLog: NSObject {
    @objc public enum Feature: Int, CaseIterable {
        case CLICK, SHOW, ACTION
        
        public var name: String {
            switch self {
            case .CLICK:
                return "click"
            case .ACTION:
                return "action"
            case .SHOW:
                return "show"
            }
        }
        
        static func featureFrom(type: String) -> Feature? {
            return Feature.allCases.filter({$0.name == type}).first
        }
    }
    
    public var name: String
    public var campaign: String
    public var feature: Feature
    public var payload: [String: Any] = [:]
    
    public init(name: String, feature: Feature, campaign: String, payload: [String : Any]) {
        self.name = name
        self.feature = feature
        self.campaign = campaign
        self.payload = payload
    }
}

サンプルコード

extension MainViewController: ShopLiveSDKDelegate {
    func log(name: String, feature: ShopLiveLog.Feature, campaign: String, payload: [String : Any]) {
        let eventLog = ShopLiveLog(name: name, feature: feature, campaign: campaign, payload: payload)
        print("eventLog \(eventLog.name)")
    }
}

• 関連リンク: Tracking User Behavior (EventLog)