تنفيذ عروض الأسعار المخصصة

العرض تتيح لك Video 360 API إدارة عروض الأسعار المخصّصة بالكامل وعمليات التنفيذ. يمكنك إنشاء خوارزميات عروض أسعار مخصّصة وتحميلها والتحقّق من صحتها. نصوص برمجية فردية، وتعيين خوارزمية محددة لمورد ما لتعرض له الاستراتيجية.

توضّح هذه الصفحة كيفية إنشاء خوارزميات عروض أسعار مخصّصة وتعديلها وتخصيصها. مع الشاشة Video 360 API: يوفر كل قسم عيّنة من التعليمات البرمجية.

إنشاء خوارزمية عروض أسعار مخصّصة

يمثّل الكائن CustomBiddingAlgorithm فردًا. التي يمكنك تخصيصها لعنصر لاستخدامه في استراتيجية عروض أسعاره. هذا النمط يحتوي على تفاصيل عن الخوارزمية، مثل customBiddingAlgorithmType و entityStatus، فضلاً عن readinessState وsuspensionState مقابل النموذج الذي ينشئه كل معلن ذي صلة. يمكنك إنشاء CustomBiddingScript و عناصر CustomBiddingAlgorithmRules كموارد فرعية للحساب التي يجب استخدامها.

في ما يلي مثال على كيفية إنشاء خوارزمية عروض أسعار مخصّصة مستندة إلى نص برمجي:

Java

// Create the custom bidding algorithm structure.
CustomBiddingAlgorithm customBiddingAlgorithm =
    new CustomBiddingAlgorithm()
        .setAdvertiserId(advertiser-id)
        .setDisplayName(display-name)
        .setEntityStatus("ENTITY_STATUS_ACTIVE")
        .setCustomBiddingAlgorithmType("SCRIPT_BASED");

// Configure the create request.
CustomBiddingAlgorithms.Create request =
    service.customBiddingAlgorithms().create(customBiddingAlgorithm);

// Create the custom bidding algorithm.
CustomBiddingAlgorithm response = request.execute();

// Display the new custom bidding algorithm name.
System.out.printf(
    "Custom bidding algorithm %s was created.%n",
    response.getName()
);

Python

# Create a custom bidding algorithm object.
custom_bidding_algorithm_obj = {
    'advertiserId': advertiser-id,
    'displayName': display-name,
    'entityStatus': 'ENTITY_STATUS_ACTIVE',
    'customBiddingAlgorithmType': 'SCRIPT_BASED'
}

# Create the custom bidding algorithm.
response = service.customBiddingAlgorithms().create(
    body=custom_bidding_algorithm_obj
).execute()

# Display the new custom bidding algorithm.
print(f'The following Custom Bidding Algorithm was created: {response}')

PHP

// Create a custom bidding algorithm object.
$customBiddingAlgorithm =
    new Google_Service_DisplayVideo_CustomBiddingAlgorithm();
$customBiddingAlgorithm->setAdvertiserId(advertiser-id);
$customBiddingAlgorithm->setDisplayName(display-name);
$customBiddingAlgorithm->setEntityStatus('ENTITY_STATUS_ACTIVE');
$customBiddingAlgorithm->setCustomBiddingAlgorithmType('SCRIPT_BASED');

// Create the custom bidding algorithm.
$result =
    $this->service->customBiddingAlgorithms->create($customBiddingAlgorithm);

// Display the new custom bidding algorithm name.
printf('Custom Bidding Algorithm %s was created.\n', $result['name']);

إدارة الوصول إلى الخوارزمية

يمكن أن تكون خوارزميات عروض الأسعار المخصّصة تابعة لشريك أو معلِن. الخوارزميات يمكن لهذا الشريك أو أي طفل الوصول إليها وتعديلها المعلنين المدرجين في الحقل sharedAdvertiserIds. يمكن الوصول إلى الخوارزميات التي يملكها معلِن وتعديلها من خلال ذلك المعلن وشريكه الرئيسي، ولكن لا يمكن مشاركته مع المعلنين الآخرين.

إذا كنت تستخدم الخوارزمية لمعلن واحد فقط، فعيّن المعلِن كمالك في الحقل advertiserId. وبخلاف ذلك، يجب تعيين الشريك الرئيسي للمعلنين بصفته المالك partnerId، وامنح المعلنين حق الوصول من خلال sharedAdvertiserIds.

تحميل منطق الخوارزمية

اعتمادًا على نوع خوارزمية عروض الأسعار المخصّصة، عليك إنشاء إما كائن نص برمجي أو كائن قواعد حيث يمكنك وتوفير المنطق للخوارزمية لاستخدامها.

تحميل نص برمجي

خوارزميات عروض الأسعار المخصّصة المستندة إلى النصوص البرمجية تستخدم الإعلانات المقدَّمة من المستخدم النصوص لتقييم قيمة مرة الظهور. نماذج من النصوص البرمجية البسيطة وقائمة من الحقول المتقدمة متوفرة من خلال الشبكة الإعلانية مركز مساعدة "فيديو 360"

توضّح الأقسام التالية كيفية إضافة نص برمجي جديد أو معدَّل إلى نص برمجي مخصّص. خوارزمية عروض الأسعار.

استرداد موقع مورد النص البرمجي

أولاً، استرداد موقع موارد متوفر ضمن عروض الأسعار المخصّصة مورد الخوارزمية مع customBiddingAlgorithms.uploadScript. هذا النمط يعرض الطلب عنصر CustomBiddingScriptRef مع اسم المورد. يمكنك حمِّل ملف النص البرمجي إلى الموقع الذي تفرضه اسم المورد. بعد ذلك، استخدِم الكائن المرجعي للنص البرمجي لعرض الأسعار المخصّص إنشاء مورد النص البرمجي

إليك مثال على كيفية استرداد موقع موارد متوفّر:

Java

// Retrieve a usable custom bidding script
// reference.
CustomBiddingScriptRef scriptRef =
    service
        .customBiddingAlgorithms()
        .uploadScript(custom-bidding-algorithm-id)
        .setAdvertiserId(advertiser-id)
        .execute();

// Display the custom bidding script reference resource path.
System.out.printf(
    "The script can be uploaded to the following resource path: %s%n",
    scriptRef.getResourceName()
);

Python

# Retrieve a usable custom bidding script reference
# object.
custom_bidding_script_ref = service.customBiddingAlgorithms().uploadScript(
    customBiddingAlgorithmId=custom-bidding-algorithm-id,
    advertiserId=advertiser-id
).execute()

# Display the new custom bidding script reference object.
print('The following custom bidding script reference object was retrieved:'
      f'{custom_bidding_script_ref}')

PHP

// Set parent advertiser ID of custom bidding
// algorithm in optional parameters array for request.
$optParams = array('advertiserId' => advertiser-id);

// Retrieve a usable custom bidding script reference.
$scriptRefResponse = $this->service->customBiddingAlgorithms->uploadScript(
    custom-bidding-algorithm-id,
    $optParams
);

// Display the new custom bidding script reference object.
printf(
    'The script can be uploaded to the following resource path: %s\n',
    $scriptRefResponse->getResourceName()
);

تحميل ملف نص برمجي

بعد استرداد موقع مورد متاح، حمّل ملف النص البرمجي إليه الموقع الجغرافي في الشاشة نظام فيديو 360 مع media.upload. تدعم هذه الطريقة عملية تحميل بسيطة تتطلّب استخدام مَعلمة طلب البحث uploadType=media

في ما يلي مثال على كيفية تحميل ملف نص برمجي مخصص تم استرداده العنصر المرجعي للنص البرمجي لعرض الأسعار:

Java

// Create media object.
GoogleBytestreamMedia media = new GoogleBytestreamMedia();
media.setResourceName(resource-name);

// Create input stream for the script file.
InputStreamContent scriptFileStream =
    new InputStreamContent(
        null, new FileInputStream(script-path));

// Create media.upload request.
Media.Upload uploadRequest =
        service
            .media()
            .upload(
                resource-name,
                media,
                scriptFileStream);

// Retrieve uploader from the request and set it to us a simple
// upload request.
MediaHttpUploader uploader = uploadRequest.getMediaHttpUploader();
uploader.setDirectUploadEnabled(true);

// Execute the upload using an Upload URL with the destination resource
// name.
uploader
    .upload(
        new GenericUrl(
            "https://displayvideo.googleapis.com/upload/media/"
                + resource-name));

Python

# Create a media upload object.
media = MediaFileUpload(script-path)

# Create upload request.
upload_request = service.media().upload(
    resourceName=resource-name, media_body=media)

# Override response handler to expect null response.
upload_request.postproc = HttpRequest.null_postproc

# Upload script to resource location given in retrieved custom bidding
# script reference object.
upload_request.execute()

PHP

// Create a media object.
$mediaBody = new Google_Service_DisplayVideo_GoogleBytestreamMedia();
$mediaBody->setResourceName(resource-name);

// Set parameters for upload request.
$optParams = array(
    'data' => file_get_contents(script-path),
    'uploadType' => 'media',
    'resourceName' => resource-name
);

// Upload script file to given resource location.
$this->service->media->upload(
    resource-name,
    $mediaBody,
    $optParams
);

cURL

curl --request POST 'https://displayvideo.googleapis.com/upload/media/resource-name?uploadType=media' 
  -H 'authorization: Bearer access-token'
  -H 'Content-Type: text/plain'
  --data-binary @script-path

إنشاء كائن نص برمجي

بعد تحميل ملف النص البرمجي، أنشئ موردًا نصيًا مخصّصًا لعروض الأسعار يستند إلى الطريقة customBiddingAlgorithms.scripts.create. تشير رسالة الأشكال البيانية يجب تمرير عنصر CustomBiddingScript في الطلب فقط تضمين الكائن CustomBiddingScriptRef على أنّه العنصر المخصّص للحقل script. يؤدي هذا إلى ربط الملف الذي تم تحميله ملف البرنامج النصي مع مورد البرنامج النصي الجديد.

إليك مثال على كيفية إنشاء مورد نص برمجي:

Java

// Create the custom bidding script structure.
CustomBiddingScript customBiddingScript =
    new CustomBiddingScript()
        .setScript(custom-bidding-script-ref);

// Create the custom bidding script.
CustomBiddingScript response =
    service
        .customBiddingAlgorithms()
        .scripts()
        .create(custom-bidding-algorithm-id, customBiddingScript)
        .setAdvertiserId(advertiser-id)
        .execute();

// Display the new script resource name
System.out.printf(
    "The following script was created: %s%n",
    response.getName());

Python

# Create a custom bidding script object.
script_obj = {
    'script': custom-bidding-script-ref
}

# Create the custom bidding script.
response = service.customBiddingAlgorithms().scripts().create(
    customBiddingAlgorithmId=custom-bidding-algorithm-id,
    advertiserId=advertiser-id,
    body=script_obj).execute()

# Display the new custom bidding script object.
print(f'The following custom bidding script was created: {response}')

PHP

// Create the custom bidding script object.
$customBiddingScript =
    new Google_Service_DisplayVideo_CustomBiddingScript();
$customBiddingScript->setScript(custom-bidding-script-ref);

// Set parameters for create script request.
$optParams = array(
    'advertiserId' => advertiser-id
);

// Create the custom bidding script.
$result = $this->service->customBiddingAlgorithms_scripts->create(
    custom-bidding-algorithm-id,
    $customBiddingScript,
    $optParams
);

// Display the new script resource name.
printf('The following script was created: %s.\n', $result->getName());

بعد إنشاء مورد نص برمجي مخصّص لعروض الأسعار، ستظهر لك يعالج "فيديو 360" البرنامج النصي للتأكد من إمكانية استخدامه بنجاح لتسجيل مرات الظهور. استرداد حالة هذه المعالجة من خلال كائن النص البرمجي state. بعد قبول النص البرمجي الجديد، سيتم حساب تبدأ خوارزمية عروض الأسعار في استخدام النص البرمجي لتسجيل قيم مرّات الظهور. هذا النمط يحدث على الفور، لذا تأكد من أنك تريد تحديث الخوارزمية قبل إنشاء مورد نص برمجي جديد.

قواعد التحميل

تستخدِم خوارزميات عروض الأسعار المخصّصة المستنِدة إلى القواعد المنطق المقدَّم في AlgorithmRules لتقييم قيمة مرة الظهور.

يتم تحميل كائنات AlgorithmRules في ملف JSON، ثم مرتبطة بخوارزمية عروض أسعار مخصّصة من خلال الكائن CustomBiddingAlgorithmRules.

استرداد موقع موارد القواعد

أولاً، استرداد موقع موارد متوفر ضمن عروض الأسعار المخصّصة مورد الخوارزمية مع customBiddingAlgorithms.uploadRules. هذا النمط يعرض الطلب عنصر CustomBiddingAlgorithmsRulesRef باستخدام اسم مورد. يمكنك تحميل قواعدك. ملف إلى الموقع الذي يحدده اسم المورد. بَعْدَ ذَلِكْ استخدام العنصر المرجعي لقواعد خوارزمية عروض الأسعار المخصّصة من أجل إنشاء قواعدك المرجع.

إليك مثال على كيفية استرداد موقع موارد متوفّر:

Java

// Create the custom bidding algorithm structure.
CustomBiddingAlgorithmRulesRef rulesRef =
    service
        .customBiddingAlgorithms()
        .uploadRules(custom-bidding-algorithm-id)
        .setAdvertiserId(advertiser-id)
        .execute();

System.out.printf(
    "The rules can be uploaded to the following resource path: %s%n",
    rulesRef.getResourceName()
);

Python

# Retrieve a usable custom bidding algorithm rules reference
# object.
custom_bidding_algorithm_rules_ref = service.customBiddingAlgorithms().uploadRules(
    customBiddingAlgorithmId=custom-bidding-algorithm-id,
    advertiserId=advertiser-id
).execute()

# Display the new custom bidding algorithm rules reference object.
print('The following custom bidding algorithm rules reference object was retrieved:'
      f' {custom_bidding_algorithm_rules_ref}')

PHP

// Set parent advertiser ID of custom bidding algorithm
// in optional parameters array for request.
$optParams = array('advertiserId' => advertiser-id);

// Retrieve a usable custom bidding algorithm rules reference.
$rulesRefResponse = $this->service->customBiddingAlgorithms->uploadRules(
    custom-bidding-algorithm-id,
    $optParams
);

// Display the new custom bidding algorithm rules reference object resource path.
printf(
    'The rules can be uploaded to the following resource path: %s\n',
    $rulesRefResponse->getResourceName()
);

تحميل ملف AlgorithmRules

بعد استرداد موقع مورد متاح، حمِّل ملف القواعد إليه الموقع الجغرافي في الشاشة نظام فيديو 360 مع media.upload. تدعم هذه الطريقة عملية تحميل بسيطة تتطلّب استخدام مَعلمة طلب البحث uploadType=media

في ما يلي مثال على كيفية تحميل ملف AlgorithmRules تم استرداده العنصر المرجعي لقواعد خوارزمية عروض الأسعار المخصّصة:

Java

// Create media object.
GoogleBytestreamMedia media = new GoogleBytestreamMedia();
media.setResourceName(resource-name);

// Create input stream for the rules file.
InputStreamContent rulesFileStream =
    new InputStreamContent(
        null, new FileInputStream(rules-file-path));

// Create media.upload request.
 Media.Upload uploadRequest =
    service
        .media()
        .upload(
            resource-name,
            media,
            rulesFileStream);

// Retrieve uploader from the request and set it to us a simple
// upload request.
MediaHttpUploader uploader = uploadRequest.getMediaHttpUploader();
uploader.setDirectUploadEnabled(true);

// Execute the upload using an Upload URL with the destination resource
// name.
uploader
    .upload(
        new GenericUrl(
            "https://displayvideo.googleapis.com/upload/media/"
                + resource-name));

Python

# Create a media upload object.
media = MediaFileUpload(rules-file-path)

# Create upload request.
upload_request = service.media().upload(
    resourceName=resource-name, media_body=media)

# Override response handler to expect null response.
upload_request.postproc = HttpRequest.null_postproc

# Upload rules file to resource location given in retrieved custom bidding
# algorithm rules reference object.
upload_request.execute()

PHP

// Create a media object.
$mediaBody = new Google_Service_DisplayVideo_GoogleBytestreamMedia();
$mediaBody->setResourceName(resource-name);

// Set parameters for upload request.
$optParams = array(
    'data' => file_get_contents(rules-file-path),
    'uploadType' => 'media',
    'resourceName' => resource-name
);

// Upload rules file to given resource location.
$this->service->media->upload(
    resource-name,
    $mediaBody,
    $optParams
);

cURL

curl --request POST 'https://displayvideo.googleapis.com/upload/media/resource-name?uploadType=media' 
  -H 'authorization: Bearer access-token'
  -H 'Content-Type: text/plain'
  --data-binary @rules-file-path

إنشاء كائن قواعد

بعد تحميل ملف JSON واحد (AlgorithmRules)، أنشِئ عرض أسعار مخصّصًا مورد قواعد الخوارزمية مع customBiddingAlgorithms.rules.create. تشير رسالة الأشكال البيانية يجب تمرير عنصر CustomBiddingAlgorithmRules في الطلب تضمين الكائن CustomBiddingAlgorithmRulesRef فقط باعتباره القيمة المخصّصة للحقل rules. يؤدي هذا إلى ربط تم تحميل ملف JSON واحد (AlgorithmRules) يحتوي على مورد القواعد الجديدة.

في ما يلي مثال على كيفية إنشاء مرجع القواعد:

Java

// Create the custom bidding algorithm rules structure.
CustomBiddingAlgorithmRules customBiddingAlgorithmRules =
    new CustomBiddingAlgorithmRules()
        .setRules(custom-bidding-algorithm-rules-ref);

// Create the rules resource.
CustomBiddingAlgorithmRules response =
    service
        .customBiddingAlgorithms()
        .rules()
        .create(custom-bidding-algorithm-id, customBiddingAlgorithmRules)
        .setAdvertiserId(advertiser-id)
        .execute();

// Display the new rules resource name.
System.out.printf(
    "The following custom bidding algorithm rules object was created: %s%n",
    response.getName());

Python

# Create the custom bidding algorithm rules object.
rules_obj = {
    'rules': custom-bidding-algorithm-rules-ref
}

# Create the rules resource.
response = service.customBiddingAlgorithms().rules().create(
    customBiddingAlgorithmId=custom-bidding-algorithm-id,
    advertiserId=advertiser-id,
    body=rules_obj).execute()

# Display the new custom bidding algorithm rules object.
print(f'The following custom bidding algorithm rules resource was created: {response}')

PHP

// Create the custom bidding algorithm rules object.
$customBiddingAlgorithmRules =
    new Google_Service_DisplayVideo_CustomBiddingAlgorithmRules();
$customBiddingAlgorithmRules->setRules(custom-bidding-algorithm-rules-ref);

// Set parameters for create rules request.
$optParams = array(
    'advertiserId' => advertiser-id
);

// Create the custom bidding algorithm rules resource.
$result = $this->service->customBiddingAlgorithms_rules->create(
    custom-bidding-algorithm-id,
    $customBiddingAlgorithmRules,
    $optParams
);

// Display the new custom bidding algorithm rules resource name.
printf('The following rules resource was created: %s.\n', $result->getName());

بعد إنشاء مورد القواعد، ستلاحظ أنّ الشبكة الإعلانية يعالج إصدار "فيديو 360" مجموعة القواعد بهدف التأكد من إمكانية استخدامه بنجاح لتسجيل مرات الظهور. استرداد الولاية هذه المعالجة من خلال الحقل state في عنصر القواعد. بعد قبول القواعد الجديدة، تبدأ خوارزمية عروض الأسعار المخصّصة في استخدام لتسجيل قيم مرات الظهور على الفور.

إذا تم رفض القواعد، يمكنك استرداد سبب الرفض من القواعد error الخاص بالكائن. في حال الرفض، يجب تعديل سيتم إصلاح الخطأ في عنصر واحد (AlgorithmRules) وتكرار عملية التحميل عند بدء عملية التحميل. من استرداد الكائن المرجعي للقواعد.

تعيين خوارزمية عروض أسعار مخصّصة

بعد إنشاء خوارزمية عروض أسعار مخصّصة، وتحميل منطق مقبول وتلبية المتطلبات اللازمة، يمكنك تعيين خوارزمية عروض الأسعار إلى استراتيجية عروض الأسعار لعنصر أو طلب إدراج.

يمكنك استخدام خوارزميات عروض الأسعار المخصّصة زيادة الإنفاق استراتيجيات عروض أسعار هدف الأداء من خلال تحديد BIDDING_STRATEGY_PERFORMANCE_GOAL_TYPE_CUSTOM_ALGO ورقم تعريف خوارزمية عروض الأسعار المخصّصة performanceGoalType و customBiddingAlgorithmId، على التوالي. اعتمادًا على استراتيجية عروض الأسعار، قد تتوفّر مَعلمات عروض أسعار أخرى أو مطلوبة.

في ما يلي مثال على كيفية تعديل عنصر لاستخدام عرض سعر تحقيق الحد الأقصى من الإنفاق استراتيجية باستخدام خوارزمية عروض أسعار مخصّصة معيّنة:

Java

// Create the line item structure.
LineItem lineItem = new LineItem();

// Create and set the bidding strategy structure.
BiddingStrategy biddingStrategy = new BiddingStrategy();
MaximizeSpendBidStrategy maxSpendBidStrategy =
    new MaximizeSpendBidStrategy()
        .setPerformanceGoalType(
            "BIDDING_STRATEGY_PERFORMANCE_GOAL_TYPE_CUSTOM_ALGO")
        .setCustomBiddingAlgorithmId(custom-bidding-algorithm-id);
biddingStrategy.setMaximizeSpendAutoBid(maxSpendBidStrategy);
lineItem.setBidStrategy(biddingStrategy);

// Configure the patch request and set update mask to only update
// the bid strategy.
LineItems.Patch request =
    service
        .advertisers()
        .lineItems()
        .patch(advertiser-id, line-item-id, lineItem)
        .setUpdateMask("bidStrategy");

// Update the line item.
LineItem response = request.execute();

// Display the custom bidding algorithm ID used in the new
// bid strategy.
System.out.printf(
    "LineItem %s now has a bid strategy utilizing custom "
        + "bidding algorithm %s%n",
    response.getName(),
    response
        .getBidStrategy()
        .getMaximizeSpendAutoBid()
        .getCustomBiddingAlgorithmId());

Python

# Create the new bid strategy object.
bidding_strategy = {
    'maximizeSpendAutoBid': {
        'performanceGoalType':
            'BIDDING_STRATEGY_PERFORMANCE_GOAL_TYPE_CUSTOM_ALGO',
        'customBiddingAlgorithmId': custom-bidding-algorithm-id
    }
}

# Create a line item object assigning the new bid strategy.
line_item_obj = {'bidStrategy': bidding_strategy}

# Update the line item with a new bid strategy.
response = service.advertisers().lineItems().patch(
    advertiserId=advertiser-id,
    lineItemId=line-item-id,
    updateMask='bidStrategy',
    body=line_item_obj).execute()

# Display the line item's new bid strategy
print(f'Line Item {response["name"]} is now using the following bid'
     f' strategy: {response["bidStrategy"]}.')

PHP

// Create the line item structure.
$lineItem = new Google_Service_DisplayVideo_LineItem();

// Create and set the bidding strategy structure.
$biddingStrategy =  new Google_Service_DisplayVideo_BiddingStrategy();
$maximizeSpendBidStrategy =
    new Google_Service_DisplayVideo_MaximizeSpendBidStrategy();
$maximizeSpendBidStrategy->setPerformanceGoalType(
    'BIDDING_STRATEGY_PERFORMANCE_GOAL_TYPE_CUSTOM_ALGO'
);
$maximizeSpendBidStrategy->setCustomBiddingAlgorithmId(
    custom-bidding-algorithm-id
);
$biddingStrategy->setMaximizeSpendAutoBid($maximizeSpendBidStrategy);
$lineItem->setBidStrategy($biddingStrategy);

// Set update mask.
$optParams = array('updateMask' => 'bidStrategy');

// Update the line item.
$result = $this->service->advertisers_lineItems->patch(
    advertiser-id,
    line-item-id,
    $lineItem,
    $optParams
);

// Display the custom bidding algorithm ID used in the new bid strategy.
printf(
    'Line Item %s now has a bid strategy utilizing custom bidding algorithm %s.\n',
    $result['name'],
    $result['bidStrategy']['maximizeSpendBidStrategy']['customBiddingAlgorithmId']
);