הטמעה של בידינג בהתאמה אישית

ב-Display & Video 360 API אפשר לנהל הטמעות של בידינג בהתאמה אישית. ניתן ליצור אלגוריתמים של בידינג בהתאמה אישית, להעלות ולאמת סקריפטים נפרדים ולהקצות אלגוריתם ספציפי למשאב בתור שיטת הבידינג שלו.

בדף זה נסביר איך ליצור, לעדכן ולהקצות אלגוריתמים של בידינג בהתאמה אישית באמצעות Display & 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.

העלאת לוגיקת אלגוריתם

בהתאם לסוג האלגוריתם של הבידינג בהתאמה אישית, בשלב הבא תצטרכו ליצור אובייקט script או אובייקט rules שבו תוכלו לספק את הלוגיקה שבה ישתמש האלגוריתם.

העלאת סקריפט

אלגוריתמים של בידינג בהתאמה אישית שמבוססים על סקריפטים משתמשים בסקריפטים שסופקו על ידי משתמשים, כדי להעריך את הערך של חשיפה. במרכז העזרה של Display & Video 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()
);

העלאה של קובץ סקריפט

אחרי אחזור של מיקום משאב זמין, מעלים את קובץ הסקריפט למיקום הזה במערכת Display & Video 360 באמצעות ה-method 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());

אחרי שיוצרים משאב מותאם אישית לסקריפט של בידינג, מערכת Display & Video 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

אחרי אחזור של מיקום משאב זמין, מעלים את קובץ הכללים למיקום הזה במערכת Display & Video 360 באמצעות ה-method 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, צריך ליצור משאב בהתאמה אישית לכללים של אלגוריתם הבידינג באמצעות method 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());

אחרי שיוצרים משאב של כללים, המערכת של Display & Video 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']
);
הקודם
אחזור פריטים של YouTube ושותפים
הבא
הפעלת פריט