SDK IMA DAI cho Roku

    1. ima
    2. ima.AdBreakInfo
    3. ima.AdEvent
    4. ima.AdInfo
    5. ima.Companion
    6. ima.CuePoint
    7. ima.Error
    8. ima.ErrorEvent
    9. ima.Player
    10. ima.StreamFormat
    11. ima.StreamInfo
    12. ima.StreamManager
    13. ima.StreamRequest
    14. ima.StreamType
    15. ima.WrapperInfo

Lớp ima

Phương thức

Các hàm chung kiểm soát SDK IMA.

disableLogging()

Tắt tính năng ghi nhật ký SDK. Tính năng ghi nhật ký sẽ được bật theo mặc định.

getStreamManager()

Trả về trình quản lý luồng nếu có. Nếu trình quản lý luồng chưa có sẵn, thì kết quả trả về sẽ là Invalid (Không hợp lệ). Nếu xảy ra lỗi khi tạo trình quản lý luồng, thì hệ thống sẽ trả về đối tượng lỗi.

Trả về object: Trình quản lý luồng hoặc đối tượng lỗi.

initSdk(settings)

Khởi động SDK.

Thông số Loại Nội dung mô tả
settings object

Đối tượng cài đặt IMA không bắt buộc.

requestStream(streamRequest)

Bắt đầu yêu cầu phát trực tuyến không đồng bộ Chế độ kiểm soát sẽ trả về ngay lập tức cho trình phát sau khi gọi phương thức này.

Trả về object: một lỗi hoặc không hợp lệ nếu không có lỗi

Thông số Loại Nội dung mô tả
streamRequest object

Trở lại đầu trang

Lớp ima.AdBreakInfo

Trường

Phương thức

Chứa thông tin về một điểm chèn quảng cáo. SDK đã truyền đến lệnh gọi lại sự kiện.

Thuộc tính

Tên Loại Nội dung mô tả
adPosition

Chỉ mục của quảng cáo trong điểm chèn quảng cáo. Sẽ là 1 cho các quảng cáo độc lập.
duration

Thời lượng ngắt tối đa tính bằng giây hoặc -1 nếu không xác định.
podIndex

Đối với sự kiện phát trực tiếp, luôn trả về -1. Đối với video theo yêu cầu (VOD), hàm sẽ trả về chỉ mục của nhóm quảng cáo. Đối với nhóm đầu video, trả về 0. Đối với quảng cáo trong video, trả về 1, 2, ..., n. Đối với nhóm cuối video, trả về n+1...n+x. Giá trị mặc định là 0 nếu quảng cáo này không thuộc một nhóm hoặc nhóm này không thuộc danh sách phát.
timeOffset

Vị trí của nhóm trong nội dung tính bằng giây. Quảng cáo trước video trả về 0, quảng cáo sau video trả về -1 và quảng cáo trong video trả về thời gian theo lịch của nhóm.
totalAds

Tổng số quảng cáo có trong điểm chèn quảng cáo này. Sẽ là 1 cho các quảng cáo độc lập.

createAdBreakInfo()


Trả về ima.AdBreakInfo:

Trở lại đầu trang

Lớp ima.AdEvent

Trường

Các sự kiện do người quản lý quảng cáo kích hoạt.

Thuộc tính

Tên Loại Nội dung mô tả
AD_PERIOD_ENDED

Được kích hoạt mỗi khi luồng chuyển từ quảng cáo hoặc phương tiện chặn sang nội dung. Mã này sẽ được kích hoạt ngay cả khi quảng cáo được phát lần thứ hai hoặc khi tìm kiếm một quảng cáo.
AD_PERIOD_STARTED

Được kích hoạt mỗi khi luồng chuyển từ nội dung sang quảng cáo hoặc phương tiện chặn. Mã này sẽ được kích hoạt ngay cả khi quảng cáo được phát lần thứ hai hoặc khi tìm kiếm một quảng cáo.
COMPLETE

Được kích hoạt khi quảng cáo phát xong.
ERROR

Được kích hoạt khi xảy ra lỗi.
FIRST_QUARTILE

Được kích hoạt khi con trỏ vị trí quảng cáo đi qua phần tư đầu tiên.
MIDPOINT

Được kích hoạt khi con trỏ vị trí quảng cáo đi qua điểm giữa.
PROGRESS

Được kích hoạt khi có cập nhật về tiến trình của một quảng cáo.
SKIPPABLE_STATE_CHANGED

Được kích hoạt khi trạng thái có thể bỏ qua của quảng cáo thay đổi.
SKIPPED

Được kích hoạt khi một quảng cáo bị bỏ qua.
START

Được kích hoạt khi quảng cáo bắt đầu phát.
THIRD_QUARTILE

Được kích hoạt khi con trỏ vị trí quảng cáo đi qua phần tư thứ ba.

Trở lại đầu trang

Lớp ima.AdInfo

Trường

Phương thức

Chứa thông tin về một quảng cáo. SDK đã truyền đến lệnh gọi lại sự kiện.

Thuộc tính

Tên Loại Nội dung mô tả
adBreakInfo

Thông tin liên quan đến toàn bộ điểm chèn quảng cáo này.
adDescription

Nội dung mô tả về quảng cáo.
adId

Mã của quảng cáo hoặc một chuỗi trống nếu không xác định.
adSystem

Hệ thống quảng cáo cung cấp mẫu quảng cáo.
adTitle

Tiêu đề của quảng cáo.
advertiserName

Tên nhà quảng cáo do bên phân phát xác định.
companions

Quảng cáo đồng hành được chỉ định trong phản hồi VAST.
currentTime

Thời gian hiện tại trong quảng cáo (tính bằng giây) hoặc -1 nếu không xác định.
duration

Thời lượng của quảng cáo này tính bằng giây hoặc -1 nếu không xác định.
universalAdIDRegistry

Một chuỗi dùng để xác định URL của trang web đăng ký có danh mục Mã quảng cáo chung của mẫu quảng cáo đã chọn.
universalAdIDValue

Mã quảng cáo chung của mẫu quảng cáo đã chọn cho quảng cáo.
wrappers

Một mảng ima.WrapperInfo có thông tin về trình bao bọc cho quảng cáo này. Thứ tự sẽ đi từ trình bao bọc bên ngoài đến trình bao bọc bên trong.

createAdInfo()


Trả về ima.AdInfo:

Trở lại đầu trang

Lớp ima.Companion

Trường

Phương thức

Chứa thông tin về quảng cáo đồng hành của một quảng cáo.

Thuộc tính

Tên Loại Nội dung mô tả
apiFramework

API cần thiết để thực thi quảng cáo này hoặc Không hợp lệ nếu không có sẵn.
creativeType

Đại diện cho loại mẫu quảng cáo thường là mimetype.
height

Chiều cao của quảng cáo đồng hành tính bằng pixel. 0 nếu không có.
trackingEvents

Sơ đồ theo dõi các sự kiện, trong đó khoá là sự kiện và giá trị là danh sách URL cần ping dựa trên sự kiện đó.
url

URL cho tài nguyên tĩnh của quảng cáo đồng hành này.
width

Chiều rộng của quảng cáo đồng hành tính bằng pixel. 0 nếu không có.

createCompanion()


Trả về ima.Companion:

Trở lại đầu trang

Lớp ima.CuePoint

Trường

Phương thức

Chứa thông tin về điểm dừng.

Thuộc tính

Tên Loại Nội dung mô tả
end

Thời gian kết thúc cho một điểm dừng tính bằng giây. Điều này tương ứng với một điểm chèn quảng cáo.
hasPlayed

Một giá trị boolean cho biết điểm dừng đã phát.
start

Thời gian bắt đầu cho một điểm dừng tính bằng giây. Điều này tương ứng với một điểm chèn quảng cáo.

createCuePoint()


Trả về ima.CuePoint:

Trở lại đầu trang

Lớp ima.Error

Trường

Phương thức

Đối tượng được chuyển đến trình xử lý lỗi nếu có lỗi.

Thuộc tính

Tên Loại Nội dung mô tả
id

Mã lỗi. Hãy xem hằng số ErrorEvent để biết danh sách các mã lỗi.
info

Thông tin bổ sung về lỗi.
type

Luôn đặt thành lỗi để cho biết loại đối tượng này.

createError()


Trả về ima.Error:

Trở lại đầu trang

Lớp ima.ErrorEvent

Trường

Tất cả lỗi mà SDK có thể gửi lại.

Thuộc tính

Tên Loại Nội dung mô tả
BAD_STREAM_REQUEST

Yêu cầu truyền trực tuyến không được điền chính xác.
COULD_NOT_LOAD_STREAM

Không thể tải luồng.
ERROR

Lỗi không xác định.
INVALID_RESPONSE

Phản hồi của máy chủ không hợp lệ.
STREAM_API_KEY_NOT_VALID

Máy chủ không chấp nhận khoá API mà bạn cung cấp.

Trở lại đầu trang

Lớp ima.Player

Phương thức

adBreakEnded(adBreakInfo)

Không bắt buộc. Được gọi khi một điểm chèn quảng cáo đã kết thúc.

Thông số Loại Nội dung mô tả
adBreakInfo ima.AdBreakInfo

Chứa thông tin về điểm chèn quảng cáo.

adBreakStarted(adBreakInfo)

Không bắt buộc. Được gọi khi một điểm chèn quảng cáo bắt đầu.

Thông số Loại Nội dung mô tả
adBreakInfo ima.AdBreakInfo

Chứa thông tin về điểm chèn quảng cáo.

allVideoComplete()

Không bắt buộc. Được gọi khi tất cả video hoàn tất.

createPlayer()

Tạo một đối tượng Player IMA trống. Bạn phải triển khai hàm loadUrl để phát quảng cáo. Các hàm khác là không bắt buộc.

Trả về ima.Player:

loadUrl(streamInfo)

Được gọi khi trình phát bắt đầu phát một URL. Bạn phải triển khai phương thức này để tải luồng.

Thông số Loại Nội dung mô tả
streamInfo ima.StreamInfo

Chứa thông tin cần thiết để phát nội dung.

Trở lại đầu trang

Lớp ima.StreamFormat

Trường

Xác định định dạng của luồng.

Thuộc tính

Tên Loại Nội dung mô tả
DASH

HLS

Trở lại đầu trang

Lớp ima.StreamInfo

Trường

Phương thức

Thông tin được chuyển từ SDK đến trình phát về luồng.

Thuộc tính

Tên Loại Nội dung mô tả
format

Định dạng video: hls hoặc dấu gạch ngang. Được xác định trong ima.StreamFormat.
manifest

URL cho luồng.
streamId

Mã nhận dạng duy nhất của luồng.
streamType

Loại video: phát trực tiếp hoặc theo yêu cầu. Được xác định trong ima.StreamType.
subtitles

Phụ đề, nếu có. Nếu không thì không hợp lệ.

createStreamInfo()


Trả về ima.StreamInfo:

Trở lại đầu trang

Lớp ima.StreamManager

Phương thức

Đối tượng để quản lý việc phát sự kiện phát trực tiếp.

addEventListener(event, callback)

Thêm trình nghe cho sự kiện được chỉ định. Xem hằng số AdEvents để biết các sự kiện được hỗ trợ.

Thông số Loại Nội dung mô tả
event string

callback function

createStreamManager(streamRequest, streamInitResponse)


Trả về ima.StreamManager:

Thông số Loại Nội dung mô tả
streamRequest ima.StreamRequest

streamInitResponse ima.StreamInitResponse

enableInteractiveAds()

Không được hỗ trợ. Thay vào đó, hãy chuyển dữ liệu trực tiếp từ quảng cáo đồng hành sang RAF. Hiện tại, đây không phải là hoạt động.

getContentTime(streamTime)

Tính năng này lấy thời gian tính bằng mili giây cho một luồng VOD, thể hiện thời gian của nội dung không có quảng cáo. Xem: https://developers.google.com/ad-manager/dynamic-ad-insertion/sdk/roku/faq Để lấy thời gian nội dung cho thời gian truyền trực tuyến hiện tại là -1.

Trả về Integer: Thời gian nội dung tương ứng với thời gian phát trực tiếp nhất định.

Thông số Loại Nội dung mô tả
streamTime Integer

Thời gian phát trực tiếp.

getCuePoints()

Trả về tất cả các điểm dừng tương ứng với tất cả các điểm chèn quảng cáo. Điều này chỉ hợp lệ đối với nội dung video theo yêu cầu, trong đó tất cả các điểm chèn quảng cáo đều biết trước. Tất cả thời gian biểu thị thời gian phát trực tiếp tính bằng giây.

Trả về Object: Một mảng có tất cả các điểm dừng.

getPreviousCuePoint(time)

Trả về điểm dừng trước thời điểm này. Điểm tín hiệu cho biết điểm chèn quảng cáo. Tất cả thời gian biểu thị thời gian phát trực tiếp tính bằng giây.

Trả về ima.CuePoint: Một đối tượng có start, end và hasPlayed. Trả về Không hợp lệ nếu không có điểm dừng.

Thông số Loại Nội dung mô tả
time Float

Thời gian tra cứu, -1 cho biết thời gian hiện tại.

getStreamTime(contentTime)

Tính năng này tính thời gian của một sự kiện phát trực tiếp từ thời điểm nội dung cho VOD (video theo yêu cầu) tính bằng mili giây. Hãy xem bài viết: https://developers.google.com/ad-manager/dynamic-ad-insertion/sdk/roku/faq

Trả về Integer: Thời gian phát trực tuyến tương ứng với thời gian phát nội dung nhất định.

Thông số Loại Nội dung mô tả
contentTime Integer

Thời gian của nội dung.

loadThirdPartyStream(streamManifest, streamSubtitle)

Tải siêu dữ liệu quảng cáo và gọi hàm loadUrl bằng dữ liệu streamManifestUrl và streamSubtitle được cung cấp. Hàm này chỉ hoạt động khi loại yêu cầu phát trực tuyến là ima.StreamType.POD_VOD.

Thông số Loại Nội dung mô tả
streamManifest string

URL tệp kê khai của luồng phát có quảng cáo được ghép.
streamSubtitle ifArray>|Invalid

Phụ đề liên kết với luồng hoặc Invalid nếu không có.

onMessage(msg)

Xử lý tất cả thông báo đến từ đối tượng Video. Phải được gọi cho mỗi thư nhận được trên roMessagePort.

Thông số Loại Nội dung mô tả
msg object

Thông báo từ cổng roVideo.

replaceAdTagParameters(adTagParameters)

Thay thế tất cả thông số thẻ quảng cáo để dùng cho các yêu cầu quảng cáo sắp tới đối với sự kiện phát trực tiếp. Xin lưu ý rằng cuộc gọi này không hoạt động đối với sự kiện phát trực tiếp VOD.

Thông số Loại Nội dung mô tả
adTagParameters string

Thông số thẻ quảng cáo mới.

start()

Bắt đầu phát sự kiện phát trực tiếp.

Trở lại đầu trang

Lớp ima.StreamRequest

Trường

Phương thức

Dùng để chỉ định các thuộc tính của yêu cầu luồng.

Thuộc tính

Tên Loại Nội dung mô tả
adTagParameters

Không bắt buộc. Bạn có thể ghi đè một tập hợp giới hạn các thông số thẻ quảng cáo trong yêu cầu luồng của mình. Phần Cung cấp tham số nhắm mục tiêu cho luồng của bạn sẽ cung cấp thêm thông tin. Bạn cũng có thể sử dụng các tham số dai-ot và dai-ov cho lựa chọn ưu tiên về biến thể của luồng. Hãy xem bài viết Ghi đè các thông số biến thể của luồng để biết thêm thông tin.
adUiNode

Nút biểu đồ cảnh nơi giao diện người dùng của quảng cáo hiển thị. IMA đặt các phần tử như nút Tại sao có quảng cáo này và Bỏ qua trên phần tử này trong quá trình chạy quảng cáo. Phần tử phải phủ toàn bộ phần tử video.
apiKey

Không bắt buộc. Bạn có thể dùng các khoá này để xác thực các yêu cầu phát trực tuyến. Khoá xác thực DAI phải được thiết lập trong giao diện người dùng DFP.
assetKey

Bắt buộc đối với sự kiện phát trực tiếp. Thuộc tính này dùng để xác định luồng nào sẽ phát. Khoá nội dung yêu cầu luồng trực tiếp là một số nhận dạng có thể được tìm thấy trong giao diện người dùng DFP.
authToken

Mã thông báo uỷ quyền yêu cầu luồng. Được dùng thay cho khoá API để uỷ quyền nội dung nghiêm ngặt hơn. Nhà xuất bản có thể kiểm soát từng hoạt động uỷ quyền luồng nội dung dựa trên mã thông báo này.
contentSourceId

Bắt buộc đối với sự kiện phát trực tiếp theo yêu cầu. cmsid đến từ Nguồn nội dung video DFP trong giao diện người dùng DFP.
customAssetKey

Khoá tài sản tuỳ chỉnh dùng để xác định xem nên phát sự kiện phát trực tiếp nào. Cần có khoá thành phần tuỳ chỉnh cho yêu cầu luồng phân phát nhóm.
format

Định dạng của luồng. Giá trị mặc định là ima.StreamFormat.HLS.
networkCode

Mã mạng cho nhà xuất bản gửi yêu cầu phát trực tuyến. Bạn cần có mã mạng cho các yêu cầu luồng phân phát nhóm.
player

Triển khai giao diện trình phát.
ppid

Không dùng nữa. Sử dụng adTagParameters. Không bắt buộc. Giá trị nhận dạng do nhà xuất bản cung cấp cho Đối tượng DFP.
streamActivityMonitorId

Mã được dùng để gỡ lỗi luồng bằng trình giám sát hoạt động phát trực tiếp. Việc này được dùng để mang đến một cách thuận tiện cho phép nhà xuất bản tìm thấy nhật ký luồng trong công cụ giám sát hoạt động phát trực tiếp.
videoId

Bắt buộc đối với sự kiện phát trực tiếp theo yêu cầu. Giá trị nhận dạng cho nguồn nội dung video.
videoObject

Đối tượng video (chẳng hạn như Video roSGNode) chịu trách nhiệm phát video trên ứng dụng. Đối tượng này sẽ được thăm dò ý kiến để nhiều dữ liệu được sử dụng trong các sự kiện HLS trực tiếp có thời gian đúng.

createLiveStreamRequest(assetKey, apiKey)

Khởi động các thuộc tính bắt buộc của StreamRequest đang hoạt động. Việc sử dụng API này sẽ khiến mọi thuộc tính khác dành riêng cho StreamType bị bỏ qua. Nếu bất kỳ tham số bắt buộc nào là chuỗi trống, thì việc ghi nhật ký lỗi sẽ xảy ra và API sẽ trả về StreamRequest chung mà không có thuộc tính nào bị bỏ qua.

Trả về ima.StreamRequest: đối tượng ima.StreamRequest có các thuộc tính Live bắt buộc.

Thông số Loại Nội dung mô tả
assetKey string

apiKey string

Tham số không bắt buộc sẽ được gán cho thuộc tính apiKey của StreamRequest trả về; mặc định là chuỗi trống.

createPodLiveStreamRequest(customAssetKey, networkCode, apiKey)

Khởi động các thuộc tính bắt buộc của ima.StreamRequest Pod Live. Việc sử dụng API này sẽ khiến mọi thuộc tính khác dành riêng cho ima.StreamType bị bỏ qua. Nếu bất kỳ tham số bắt buộc nào là chuỗi trống, thì việc ghi nhật ký lỗi sẽ xảy ra và API sẽ trả về StreamRequest chung mà không có thuộc tính nào bị bỏ qua.

Trả về StreamRequest: đối tượng ima.StreamRequest có các thuộc tính PodLive bắt buộc.

Thông số Loại Nội dung mô tả
customAssetKey string

networkCode string

apiKey string

Tham số không bắt buộc sẽ được gán cho thuộc tính ima.StreamRequest.apiKey của ima.StreamRequest được trả về; giá trị mặc định là chuỗi trống.

createPodVodStreamRequest(networkCode)

Khởi động các thuộc tính bắt buộc của ima.StreamRequest để đăng ký luồng VOD khi sử dụng tính năng phân phát nhóm DAI với công cụ kết hợp video của bên thứ ba. Hàm này đặt loại yêu cầu thành ima.StreamType.POD_VOD và xác thực tất cả các thuộc tính bắt buộc đối với dữ liệu bị thiếu. Những lần xác thực không thành công sẽ ghi lại một lỗi trong bảng điều khiển gỡ lỗi.

Trả về StreamRequest: một đối tượng ima.StreamRequest. Nếu bạn đã chỉ định tất cả các thuộc tính bắt buộc, thì loại yêu cầu sẽ được đặt thành ima.StreamType.POD_VOD.

Thông số Loại Nội dung mô tả
networkCode string

mã mạng Google Ad Manager

createStreamRequest()


Trả về ima.StreamRequest: Một đối tượng ima.StreamRequest trống.

createVideoStitcherLiveStreamRequest(customAssetKey, networkCode, liveConfigId, region, projectNumber, oAuthToken)

Khởi động các thuộc tính bắt buộc của Video Kết hợp video đang phát trực tiếp StreamRequest. Việc sử dụng API này sẽ khiến mọi thuộc tính khác cụ thể của StreamType bị bỏ qua. Nếu bất kỳ tham số bắt buộc nào là chuỗi trống, thì việc ghi nhật ký lỗi sẽ xảy ra và API sẽ trả về StreamRequest chung mà không có thuộc tính nào bị bỏ qua.

Trả về ima.StreamRequest: đối tượng ima.StreamRequest có các thuộc tính VideoStitcherLive bắt buộc.

Thông số Loại Nội dung mô tả
customAssetKey string

networkCode string

liveConfigId string

region string

projectNumber string

oAuthToken string

createVideoStitcherVodStreamRequest(adTagUrl, networkCode, contentSourceUrl, region, projectNumber, oAuthToken)

Khởi động các thuộc tính bắt buộc của video VOD trong Công cụ kết hợp video StreamRequest. Việc sử dụng API này sẽ khiến mọi thuộc tính khác cụ thể của StreamType bị bỏ qua. Nếu bất kỳ tham số bắt buộc nào là chuỗi trống, thì việc ghi nhật ký lỗi sẽ xảy ra và API sẽ trả về StreamRequest chung mà không có thuộc tính nào bị bỏ qua.

Trả về ima.StreamRequest: đối tượng ima.StreamRequest có các thuộc tính VideoStitcherVod bắt buộc.

Thông số Loại Nội dung mô tả
adTagUrl string

networkCode string

contentSourceUrl string

region string

projectNumber string

oAuthToken string

createVodStreamRequest(contentSourceId, videoId, apiKey)

Khởi động các thuộc tính bắt buộc của VOD ima.StreamRequest. Việc sử dụng API này sẽ khiến mọi thuộc tính khác dành riêng cho ima.StreamType bị bỏ qua. Nếu bất kỳ tham số bắt buộc nào là chuỗi trống, thì việc ghi nhật ký lỗi sẽ xảy ra và API sẽ trả về StreamRequest chung mà không có thuộc tính nào bị bỏ qua.

Trả về ima.StreamRequest: đối tượng ima.StreamRequest có các thuộc tính VOD bắt buộc.

Thông số Loại Nội dung mô tả
contentSourceId string

videoId string

apiKey string

Tham số không bắt buộc sẽ được gán cho thuộc tính ima.StreamRequest.apiKey của ima.StreamRequest được trả về; giá trị mặc định là chuỗi trống.

Trở lại đầu trang

Lớp ima.StreamType

Trường

Xác định loại luồng mà trình phát được yêu cầu phát. Quảng cáo trước video và video theo yêu cầu nên phát từ đầu sự kiện phát trực tiếp.

Thuộc tính

Tên Loại Nội dung mô tả
LIVE

Video này đã xuất hiện công khai.
VOD

Video theo yêu cầu.

Trở lại đầu trang

Lớp ima.WrapperInfo

Trường

Phương thức

Chứa thông tin về một trình bao bọc.

Thuộc tính

Tên Loại Nội dung mô tả
adId

Mã của quảng cáo hoặc một chuỗi trống nếu không xác định.
adSystem

Tên đã khai báo của hệ thống quảng cáo hoặc và chuỗi trống nếu không xác định.
creativeAdId

Mã quảng cáo trên mẫu quảng cáo hoặc một chuỗi trống nếu không xác định.
creativeId

Mã của mẫu quảng cáo hoặc một chuỗi trống nếu không xác định.
dealId

Mã giao dịch hoặc chuỗi trống nếu không xác định.

createWrapperInfo()


Trả về ima.WrapperInfo:

Trở lại đầu trang