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

באמצעות 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.

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

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

אחרי שיוצרים משאב כללים, מערכת 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']
);