Ads Plugin for ByteArk Player SDK iOS

• Ads Plugin for ByteArk Player SDK iOS
  • คุณสมบัติ
  • ความต้องการ ของ Plugin
  • การติดตั้ง Plugin
    • CocoaPods (แนะนำ)
    • Swift Package Manager
  • การใช้งาน
    • การใช้งาน API ของ Plugin
      • Methods
      • Variables
    • Listen plugin's events

คุณสมบัติ

• Integrated Google IMA SDK เข้ากับ ByteArk Player SDK for iOS เพื่อให้สามารถเล่นวิดีโอโฆษณาในรูปแบบ VAST ได้

ความต้องการ ของ Plugin

• iOS 14 หรือสูงกว่า
• XCode
• Swift 5.5
• ByteArkPlayerSDK version >= 0.2.1

การติดตั้ง Plugin

CocoaPods (แนะนำ)

CocoaPods (opens new window) เป็นเครื่องมือจัดการ dependencies สำหรับโปรเจกต์ Cocoa คุณสามารถติดตั้งได้ด้วยคำสั่งดังนี้:

gem install cocoapods

การติดตั้ง Ads Plugin ด้วย Cocoapods

1. รันคำสั่งต่อไปนี้เพื่อเพิ่ม ByteArk Player SDK สำหรับ iOS ลงใน Cocoapods repo:

pod repo add byteark-player-sdk-ios-specs https://github.com/byteark/byteark-player-sdk-ios-specs.git

2. แก้ไขไฟล์ Podfile โดยเพิ่มบรรทัดต่อไปนี้ที่จุดเริ่มต้นของไฟล์:

source 'https://github.com/CocoaPods/Specs.git'
source 'https://github.com/byteark/byteark-player-sdk-ios-specs.git'

3. กำหนดแพลตฟอร์มเป็น iOS 14:

platform :ios, '14.0'

4. เพิ่มบรรทัดต่อไปนี้ลงในไฟล์ Podfile:

pod 'ByteArkPlayerSDKAdsPlugin', '~> BYTEARK_PLAYER_SDK_ADS_PLUGIN_VERSION'

Note

แทนที่ BYTEARK_PLAYER_SDK_ADS_PLUGIN_VERSION ด้วยหมายเลขเวอร์ชันของ ByteArkPlayerSDKAdsPlugin ที่คุณต้องการใช้

1. รันคำสั่ง pod install ใน Terminal:

pod install

Note

Cocoapods จะติดตั้ง SDK โดยตรงจาก Github private repository โดยใช้ ssh key หากคุณยังไม่ได้ตั้งค่า ssh key ในบัญชี Github ของคุณ โปรดดูเอกสาร Adding a new SSH key to your GitHub account (opens new window) บนเว็บไซต์ของ Github

Swift Package Manager

ใช้ Swift Package Manager เพื่อติดตั้ง Ads Plugin และ Google IMA SDK.

1. ใน Xcode ไปที่เมนู File > Add Packages
2. ใส่ URL: https://github.com/byteark/byteark-player-sdk-ios
3. เลือกเวอร์ชันของ Ads Plugin
4. เมื่อเสร็จสิ้น Xcode จะดาวน์โหลดปลั๊กอินโดยอัตโนมัติ
5. Add Google IMA SDK dependencies https://developers.google.com/interactive-media-ads/docs/sdks/ios/client-side#spm

การใช้งาน

import UIKit
import ByteArkPlayerSDK
// Step 1: Import the necessary plugins for ads integration
import ByteArkPlayerSDKAdsPlugin
class PlayerViewController: ByteArkPlayerViewController, ByteArkPlayerAdsPluginDelegate {
    override func viewDidLoad() {
        super.viewDidLoad()
        // Step 2: Set up the ad tag URL for VAST ads
        let adTagUrl = "https://pubads.g.doubleclick.net/gampad/ads?iu=/21775744923/external/vmap_ad_samples&sz=640x480&cust_params=sample_ar%3Dpremidpostpod&ciu_szs=300x250&gdfp_req=1&ad_rule=1&output=vmap&unviewed_position_start=1&env=vp&impl=s&cmsid=496&vid=short_onecue&correlator="
        do {
            // Step 3: Create a ByteArkPlayerAdsConfig using ByteArkPlayerAdsConfigBuilder and set the VAST ad tag URL
            let adsConfig = try ByteArkPlayerAdsConfigBuilder(adsTagUrl: adTagUrl).build()
            // Step 4: Create a ByteArkPlayerAdsPlugin instance using the config from step 3
            let adsPlugin = ByteArkPlayerAdsPlugin(with: adsConfig)
            // Step 5: Assign the ByteArkPlayerAdsPluginDelegate to receive ad callback events
            adsPlugin.delegate = self
            // Step 6: Set up the media item using ByteArkPlayerItemBuilder
            let item = try ByteArkPlayerItemBuilder()
                        .media(URL(string: "https://byteark-playertzxedwv.stream-playlist.byteark.com/streams/TZyZheqEJUwC/playlist.m3u8")!)
                        .title("Big Buck Bunny")
                        .build()
            // Step 7: Configure the player using ByteArkPlayerConfigBuilder, add the ads plugin to the config
            let config = try ByteArkPlayerConfigBuilder()
                .item(item)
                .autoplay(true)
                .addPlugin(plugin: adsPlugin, name: ByteArkPlayerAdsPlugin.PluginName) // Adding the ads plugin
                .build()
            // Step 8: Apply the configuration to the player
            player.configure(with: config)
        } catch {
            print(error.localizedDescription)
        }
    }
    // MARK: - ByteArkPlayerAdsPluginDelegate Methods
    // Step 9: Implement the ads delegate method to handle when ads are loaded
    func adsLoader(_ loader: IMAAdsLoader, adsLoadedWith adsLoadedData: IMAAdsLoadedData) {
        print("Ads loaded successfully.")
    }
}

การใช้งาน API ของ Plugin

Plugin นี้มีเมธอดและตัวแปรที่สามารถเรียกใช้งานจาก instance ของ Plugin เพื่อควบคุมพฤติกรรมหรือดึงข้อมูลได้

Methods

Name	Description
func playAd(adTagUrl url: String, adType: ByteArkPlayerAdsPluginAdsType?)	Play ad
func skipAd()	Skip current ad

Variables

Name	Description
var delegate: ByteArkPlayerAdsPluginDelegate? { get, set }	Get/Set a ads plugin delegate
var isAdsPlaying : Bool { get}	Check is ads playing
var adMetadata: ByteArkPlayerAdMetadata? { get }	Get the ad metadata

Listen plugin's events

/// A protocol which must be used to monitor playback event from IMA instance
@objc public protocol ByteArkPlayerAdsPluginDelegate {
    /// Fired when ads requested
    @objc optional func adsRequest(_ request: IMAAdsRequest)
    /// Fired when ads loaded
    @objc optional func adsLoader(_ loader: IMAAdsLoader, adsLoadedWith adsLoadedData: IMAAdsLoadedData)
    /// Fired when ads load fail
    @objc optional func adsLoadFail(_ loader: IMAAdsLoader, failedWith adErrorData: IMAAdLoadingErrorData)
    /// Fired when IMA SDK is going to play ads, so pause the content.
    @objc optional func adsManagerDidRequestContentPause()
    /// Fired when IMA SDK is done playing ads (at least for now), so resume the content.
    @objc optional func adsManagerDidRequestContentResume()
    /// Fired when IMA manager receive an event
    @objc optional func didReceiveEvent(_ adsManager: IMAAdsManager, didReceive event: IMAAdEvent)
    /// Fired when IMA manager give an error
    @objc optional func didReceiveError(_ adsManager: IMAAdsManager, didReceive error: IMAAdError)
    /// Fired every 200ms to provide time updates for the current ad.
    @objc optional func adsManager(_ adsManager: IMAAdsManager, adDidProgressToTime mediaTime: TimeInterval, totalTime: TimeInterval)
    /// Fired when the current ad is sufficiently buffered such that ad playback is not likely to outrun the buffer.
    @objc optional func adsManagerAdPlaybackReady(_ adsManager: IMAAdsManager)
    /// Fired when an ad that already started playing has stopped to buffer.
    @objc optional func adsManagerAdDidStartBuffering(_ adsManager: IMAAdsManager)
    /// Fired as an ad buffers. This method is called repeatedly as long as an ad is buffering.
    @objc optional func adsManager(_ adsManager: IMAAdsManager, adDidBufferToMediaTime mediaTime: TimeInterval)
    /// Fired when open link on ads
    @objc optional func linkOpenerWillOpenExternalApplication(_ linkOpener: NSObject)
}