附加廣告查詢參數與原生 SDK

在本主題中，您將學習如何使用 Brightcove 原生播放程式 SDK 將廣告查詢參數附加至您的 VMAP URL。

概覽

即使Native Player SDK不執行客戶端宏替換，您也可以手動附加查詢字符串參數以進行廣告定位。可以針對客戶端廣告或服務器端廣告執行此操作。

要了解有關網址參數的更多信息，請參見廣告變量視頻雲SSAI廣告配置API文檔中的“部分”。

客戶端廣告

您可以通過附加到VMAP URL的URL參數提供自定義值。

安卓實作

廣告定位鍵/值對可以通過兩種方式添加到廣告代碼網址中：

  • 將您的鍵/值對直接添加到廣告代碼網址。Google IMA允許使用以下方式添加廣告定位鍵/值對：cust_params參數。有關詳細信息，請參見Google的將鍵值添加到主視頻廣告代碼文件。
  • 使用，將值映射應用於廣告代碼網址updateAdTargetingValues方法GoogleIMAComponent。

對於這兩種方法，鍵/值對都將添加到廣告代碼網址的ADS_REQUEST_FOR_VIDEO事件監聽器。下面的代碼示例使用以下命令添加鍵/值對：updateAdTargetingValues方法GoogleIMAComponent。

這是使用以下代碼創建鍵/值對映射的代碼CUSTOM_FIELDS的屬性Video的對象屬性ADS_REQUEST_FOR_VIDEO事件：

Video video = (Video) event.getProperties().get(Event.VIDEO);
if (video != null) {
    Map<String, String> customFieldsMap = (HashMap<String, String>) video.getProperties().get(Video.Fields.CUSTOM_FIELDS);
}

這是針對ADS_REQUEST_FOR_VIDEO事件監聽器，已添加到Google IMA插件的設置方法中：

eventEmitter.on(GoogleIMAEventType.ADS_REQUEST_FOR_VIDEO, event -> {
    // Create a container object for the ads to be presented.
    AdDisplayContainer container = sdkFactory.createAdDisplayContainer();
    container.setPlayer(googleIMAComponent.getVideoAdPlayer());
    container.setAdContainer(brightcoveVideoView);
    // Build an ads request object and point it to the ad
    // display container created above.
    AdsRequest adsRequest = sdkFactory.createAdsRequest();

    // Set Ad Targeting values, using the Video object's Custom Fields
    // (if they are present; if they are not present, use default values instead) 
    Video video = (Video) event.getProperties().get(Event.VIDEO);
    if (video != null) {
        Map<String, String> customFieldsMap = (HashMap<String, String>) video.getProperties().get(Video.Fields.CUSTOM_FIELDS);
        if (customFieldsMap != null) { 
            googleIMAComponent.updateAdTargetingValues(customFieldsMap);
        }
    }

    adsRequest.setAdTagUrl(adRulesURL);
    adsRequest.setAdDisplayContainer(container);
    ArrayList<AdsRequest> adsRequests = new ArrayList<AdsRequest>(1);
    adsRequests.add(adsRequest);
    // Respond to the event with the new ad requests.
    event.properties.put(GoogleIMAComponent.ADS_REQUESTS, adsRequests);
    eventEmitter.respond(event);
});

iOS 實作

要將廣告查詢參數附加到iOS的Native SDK中，請按照以下步驟操作：

  1. 從使用Brightcove Native SDK進行IMA廣告的客戶端代碼示例開始：

  2. 在調用IMA插件之前，將URL查詢參數附加到VMAP URL。可以在使用以下方法之前完成此操作：

    for video in mutablePlaylist.videos {
  if let _video = video as? BCOVMutableVideo {
     _video.properties[kBCOVIMAAdTag] = IMAConfig.VMAPResponseAdTag
    updatedVideos.append(_video)
  }
}

服務器端廣告

要通過附加到VMAP URL的URL參數提供自定義值，請按照以下步驟操作：

  1. 使用 SSAI 廣告組態識別碼，從布萊特灣目錄 (播放 API) 擷取視訊物件。了解如何使用來創建廣告配置使用Native Player SDK實施服務器端廣告文件。

    廣告配置示例如下所示：

    {
  "name": "SSAI VMAP Ad Server",
  "vmap_response_namespace": "bc",
  "config_id": "your ad config Id",
  "account_id": "1752604059001",
  "created_timestamp": "2017-10-24T20:21:55.106488973Z",
  "updated_timestamp": "2017-10-26T14:26:22.161791419Z",
  "ad_config": {
  	"enable_ads": true,
  	"expected_ad_response": "dfp_vmap",
  	"proxy_beacons_enabled": false,
  	"template_url": {
  		"template": "https://solutions.brightcove.com/bcls/brightcove-player/vmap/simple-vmap.xml"
  	}
  }
}

  2. 在對Playback API的調用的jsonResponse中，檢查視頻對象的源。每個源對象將包含一個VMAP屬性和一個VMAP URL。選擇並提取VMAP URL。

    http://ssaiplayback.prod.boltdns.net/playback/once/v1/vmap/hls/v3/clear/3981276734001/
  b871a6b8-4b3e-4787-b176-aed923287d5a/477b1308-fc18-47a6-bb99-6cb9e2ff2040/
  content.vmap?bc_token=XXX

  3. 假設您的廣告網址如下所示：

    https://myad.com/ads?rule=&id=

    如果您的廣告網址包含上述廣告宏，那麼您將使用適當的值將這些查詢參數添加到VMAP網址中。

  4. 將查詢參數附加至 VMAP URL。在此示例中，廣告網址中的宏替換為值discos-enabled和宏將替換為視頻ID值。

    http://ssaiplayback.prod.boltdns.net/playback/once/v1/vmap/hls/v3/clear/3981276734001/
b871a6b8-4b3e-4787-b176-aed923287d5a/477b1308-fc18-47a6-bb99-6cb9e2ff2040/
content.vmap?bc_token=XXX&rule=discos-enabled&video_id=5625751316001
  5. 使用SSAI插件處理視頻。

  6. 有關開發的詳細信息，請參見以下內容：

安卓實作

從播放 API 回應中，您可以擷取適當的 VMAP 來源 URL 並附加查詢參數。為此，請按照下列步驟操作：

  1. 使用 SSAI 廣告組態識別碼，從布萊特灣目錄 (播放 API) 擷取視訊物件。有關詳細信息，請參見Android實施“使用Native Player SDK實施服務器端廣告”部分。

  2. 在裡面Catalog的onVideo回調方法，從中選擇並提取適當的VMAP URL Video對象的默認來源，使用SSAISourceSelector。返回的源對象應具有VMAP URL屬性。 

    SSAISourceSelector sourceSelector = new SSAISourceSelector();
Source source = sourceSelector.selectSource(video);            
String vmapUrl = source.getStringProperty(Source.Fields.VMAP);

  3. 將查詢參數附加到VMAP URL： 

    private String configureVmapUrlWithCustomParams(String vmapUrl, Map<String, String> vmapUrlParams) {
    Uri.Builder vmapBuilder = Uri.parse(vmapUrl).buildUpon();
    for (Map.Entry<String, String> entry : vmapUrlParams.entrySet()) {
        vmapBuilder.appendQueryParameter(entry.getKey(), entry.getValue());
    }
    return vmapBuilder.toString();
}

  4. 處理更新的Video帶有SSAI插件的對象，如下所示： 

    plugin.processVideo(video);

這是一個完整的代碼示例：

HttpRequestConfig httpRequestConfig = new HttpRequestConfig.Builder()
        .addQueryParameter(AD_CONFIG_ID_QUERY_PARAM_KEY, AD_CONFIG_ID_QUERY_PARAM_VALUE)
        .build();
Map<String, String> vmapUrlParams = new HashMap<>();
vmapUrlParams.put("section", "sports");
vmapUrlParams.put("multi", "baseball,tennis");

catalog.findVideoByID(getString(R.string.video_id), httpRequestConfig, new VideoListener() {
    @Override public void onVideo(Video video) {
        // The Video Sources will have a VMAP url which will be processed by the SSAI plugin,
        // If there is not a VMAP url, or if there are any requesting or parsing error,
        // an EventType.ERROR event will be emitted.
        try{
            SSAISourceSelector sourceSelector = new SSAISourceSelector();
            Source source = sourceSelector.selectSource(video);
            String vmapUrl = source.getStringProperty(Source.Fields.VMAP);
            source.getProperties().put(Source.Fields.VMAP, configureVmapUrlWithCustomParams(vmapUrl, vmapUrlParams)); plugin.processVideo(video);
        }
        catch (NoSourceFoundException ns) {
            Log.e(TAG, "No usable source was found - " + ns.getMessage());
        }
    }
});

private String configureVmapUrlWithCustomParams(String vmapUrl, Map<String, String> vmapUrlParams) {
    Uri.Builder vmapBuilder = Uri.parse(vmapUrl).buildUpon();
    for (Map.Entry<String, String> entry : vmapUrlParams.entrySet()) {
        vmapBuilder.appendQueryParameter(entry.getKey(), entry.getValue());
    }
    return vmapBuilder.toString();
}

iOS 實作

從播放 API 回應中，您可以擷取適當的 VMAP 來源 URL 並附加查詢參數。為此，請按照下列步驟操作：

  1. 使用 SSAI 廣告組態識別碼，從布萊特灣目錄 (播放 API) 擷取視訊物件。有關詳細信息，請參見iOS實施“使用Native Player SDK實施服務器端廣告”部分。

  2. 從視頻對像中，選擇並提取適當的清單或VMAP URL。從播放服務響應中，jsonResponse（NSDictionary）包含BCOV視頻對象，其中包括保存VMAP文檔URL的源。您的代碼可能類似於以下內容：

    // Create a mutable version of the jsonResponse NSDictionary object
NSURLComponents *components = [[NSURLComponents alloc] init];
NSMutableDictionary *videoPropertiesDictionary = [[NSMutableDictionary alloc] init];
NSMutableArray *updatedSources = [[NSMutableArray alloc] init];

// Define the URL parameters that will be added to the VMAP URL
NSURLQueryItem *queryItemEntrypointUrlParameter = [NSURLQueryItem queryItemWithName:@"rule" value:@"discos-enabled"];
NSURLQueryItem *queryItemVideoId = [NSURLQueryItem queryItemWithName:@"video_id" value:jsonResponse[@"id"]];

//deserialize the video and store in dictionary
[videoPropertiesDictionary addEntriesFromDictionary:jsonResponse];

  3. 將查詢參數附加至 VMAP URL。

    // For each source, update each VMAP URL stored in the jsonResponse NSDictionary object and assemble the NSURLQueryItem. Store it in the mutable version of the jsonResponse NSDictionary object.
for (NSDictionary *source in videoPropertiesDictionary[@"sources"])
{
    NSMutableDictionary *mutableSource = [[NSMutableDictionary alloc] init];
    [mutableSource addEntriesFromDictionary:source];

    NSString *vmapURL = mutableSource[@"vmap"];
    components = [NSURLComponents componentsWithString:vmapURL];

    NSArray *queryItemsArray = components.queryItems;
    NSURLQueryItem *bctoken = [queryItemsArray firstObject];
    components.queryItems = @[bctoken, queryItemEntrypointUrlParameter, queryItemVideoId ];
    mutableSource[@"vmap"] = components.URL.absoluteString;

    [updatedSources addObject:mutableSource];
}

  4. 使用SSAI插件處理修改後的URL，如下所示：

    videoPropertiesDictionary[@"sources"] = updatedSources;
// Create a new video object with the updated jsonResponse NSDictionary object
BCOVVideo *video = [BCOVPlaybackService videoFromJSONDictionary:videoPropertiesDictionary];
// Setting this video object to the BCOVPlaybackController will call the new vmap URL (with the URL parameters appended) when playback starts.
[self.controller setVideos:@[video]];