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

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

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

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

يمثّل عنصر CustomBiddingAlgorithm خوارزمية فردية يمكنك تعيينها إلى عنصر حملة لاستخدامها في استراتيجية عروض الأسعار. يحتوي هذا العنصر على تفاصيل حول الخوارزمية، مثل customBiddingAlgorithmType وentityStatus وcustomBiddingAlgorithmState. يمكنك إنشاء عناصر CustomBiddingScript كموارد فرعية ليستخدمها الخوارزمية.

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

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=algorithm_obj
).execute()

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

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

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

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

تحميل نص

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

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

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

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

في ما يلي مثال على كيفية استرداد موقع جغرافي لمورد متاح:

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}')

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

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

في ما يلي مثال على كيفية تحميل ملف نص برمجي مع توفّر مرجع كائن نص برمجي مخصّص تم استرجاعه:

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()

إنشاء عنصر نص برمجي

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

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

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}')

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

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

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

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

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

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"]}.')