آلية

يقدّم هذا الدليل نظرة عامة على مستوى عالٍ حول كيفية استخدام ميزات الحملات المباشرة الآلية من خلال واجهة برمجة التطبيقات. ويوضّح كيفية إنشاء اقتراح وكيفية تنفيذ المفاوضات.

Primer

يشبه الاقتراح الآلي طلبًا في "مدير إعلانات Google". تحتوي الاقتراحات الآلية على معلومات عامة عن معاملة مقترَحة بينك وبين أحد المشترين. يمثل العرض، مع عناصره، عرضًا للمخزون المشتري.

لمزيد من المعلومات، يُرجى الاطّلاع على مركز المساعدة.

إنشاء اقتراح عبر واجهة برمجة التطبيقات

لإنشاء عنصر Proposal، يجب فقط تحديد الاسم والمشتري الآلي مطلوبة. يمكن الحصول على رقم تعريف المشتري الآلي من خلال واجهة المستخدم أو Programmatic_Buyer جدول PQL.

Java

Proposal proposal = new Proposal();

// Setting required Marketplace information.
ProposalMarketplaceInfo proposalMarketplaceInfo = new ProposalMarketplaceInfo();
proposalMarketplaceInfo.setBuyerAccountId(programmaticBuyerId);

// Set common required fields for a proposal.
proposal.setName("Proposal #" + new Random().nextInt(Integer.MAX_VALUE));
proposal.setPrimaryTraffickerId(primaryTraffickerId);
proposal.setMarketplaceInfo(proposalMarketplaceInfo);
    

عرض على GitHub

Python

proposal = {
    # Setting required Marketplace information.
    'isProgrammatic': 'true',
    'marketplaceInfo': {
        'buyerAccountId': programmatic_buyer_id,
    },
    # Set common required fields for proposals.
    'name': 'Proposal #%s' % uuid.uuid4(),
    # ...
}
    

عرض على GitHub

PHP

$proposal = new Proposal();
$proposal->setName('Proposal #' . uniqid());

// Set the required Marketplace information.
$proposalMarketplaceInfo = new ProposalMarketplaceInfo();
$proposalMarketplaceInfo->setBuyerAccountId($buyerId);
$proposal->setMarketplaceInfo($proposalMarketplaceInfo);
    

عرض على GitHub

#C

// Create a proposal with the minimum required fields.
Proposal proposal = new Proposal()
{
    name = "Programmatic proposal #" + new Random().Next(int.MaxValue),
    // Set required Marketplace information
    marketplaceInfo = new ProposalMarketplaceInfo()
    {
        buyerAccountId = programmaticBuyerId
    }
};
    

عرض على GitHub

Ruby

# Create proposal configuration object.
proposal = {
  :marketplace_info => {
    :buyer_account_id => buyer_id
  },
  :name => 'Proposal %s' % SecureRandom.uuid(),
  # ...
}
    

عرض على GitHub

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

Java

SalespersonSplit primarySalesperson = new SalespersonSplit();
primarySalesperson.setUserId(primarySalespersonId);
proposal.setPrimarySalesperson(primarySalesperson);
    

عرض على GitHub

Python

'primarySalesperson': {
    'userId': primary_salesperson_id,
},
'primaryTraffickerId': primary_trafficker_id,
'probabilityOfClose': '100000',
    

عرض على GitHub

PHP

// Create salesperson splits for the primary salesperson.
$primarySalesperson = new SalespersonSplit();
$primarySalesperson->setUserId($primarySalespersonId);
$proposal->setPrimarySalesperson($primarySalesperson);

// Set the primary trafficker on the proposal for when it becomes an
// order.
$proposal->setPrimaryTraffickerId($primaryTraffickerId);

$advertiser = new ProposalCompanyAssociation();
$advertiser->setType(
    ProposalCompanyAssociationType::ADVERTISER
);
$advertiser->setCompanyId($advertiserId);
$proposal->setAdvertiser($advertiser);
    

عرض على GitHub

#C

// Set fields that are required before sending the proposal to the buyer.
proposal.primaryTraffickerId = primaryTraffickerId;
proposal.sellerContactIds = new long[] { primarySalespersonId };
proposal.primarySalesperson = new SalespersonSplit()
{
    userId = primarySalespersonId,
};
proposal.advertiser = new ProposalCompanyAssociation()
{
    type = ProposalCompanyAssociationType.ADVERTISER,
    companyId = advertiserId
};
    

عرض على GitHub

Ruby

:primary_salesperson => {
  :user_id => primary_salesperson_id
},
:primary_trafficker_id => primary_trafficker_id
    

عرض على GitHub

نظرًا لأن العروض تتكون بشكل عام من ProposalLineItem ستكون الخطوة التالية هي إضافة عناصر عرض أسفل عناصر إنشاء اقتراح.

حالات العرض الآلي

يوضح الشكل التالي اقتراحًا آليًا في نقاط مختلفة أثناء عملية التفاوض من وجهة نظر واجهة برمجة التطبيقات. يتم تمثيل كل ولاية مجموعات مختلفة من الحقول التالية:

• ProposalMarketplaceInfo.hasLocalVersionEdits
• ProposalMarketplaceInfo.negotiationStatus
• Proposal.status

لمزيد من المعلومات، يُرجى الاطّلاع على مركز مساعدة "مدير الإعلانات".

الشكل 1: حالات اقتراح آلي

جولة تفصيلية حول التفاوض

سنرشدك هنا إلى كيفية استخدام واجهة برمجة التطبيقات لإكمال التفاوض عرض آلي مع مشترٍ. سنشير إلى الحالات في المخطّط العميق أعلاه.

التحضير لمراجعة المشتري أو قبوله

عليك أولاً صياغة مقترح آلي مع عناصر العرض التي تريد إرسالها إلى مشترٍ. تمثّل هذه السمة state C في الشكل أعلاه.

طلب مراجعة المشتري أو قبوله

عندما تكون مستعدًا لمطالبة المشتري بمراجعة اقتراح الإعلان الآلي، يمكنك RequestBuyerReview أو RequestBuyerAcceptance باستخدام ProposalService.performProposalAction سينقلك هذا إلى مرحلة التفاوض.

التفاوض

في هذه المرحلة، قد تحدث بعض الأمور.

• يمكن للمشتري قبول عرض الإعلان الآلي بدون إجراء تغييرات.
• يجوز أن يقترح المشتري تغييرات. في هذه الحالة، ستتم إعادة إرسال الاقتراح إلى حالة مسودة (state B في الشكل 1). ستحتاج بعد ذلك إلى فتح اقتراح التعديل، وإجراء التغييرات المقترحة وإعادة إرسالها للمراجعة من قبل المشتري.
• ويمكنك أيضًا أن تقرّر إجراء تغييرات حتى قبل أن يردّ المشتري. يمكنك ويتم ذلك عن طريق فتح اقتراح التعديل من state D في الشكل 1.

ملاحظة: عندما يكون اقتراح آلي متاحًا للتعديل (state A في الشكل 1)، لن يتلقّى آخر الأخبار تلقائيًا من "السوق". هذا يعني أنه إذا كانت يُجري المشتري تغييرًا قبل طلب قبول المشتري، ستتلقى رسالة خطأ NEW_VERSION_FROM_BUYER عند محاولة طلب قبول المشتري. لحلّ هذه المشكلة، عليك تنفيذ الإجراء DiscardProposalDrafts، الذي سيؤدي إلى استبدال التعديلات المحلية بآخر تغييرات المشتري من السوق. عليك بعد ذلك إعادة تطبيق التعديلات المحلية.

وتستمر هذه التفاوض حتى تتوصّل إلى اتفاق مع المشتري. تعليقات بينك وبين المشتري باستخدام getMarketplaceCommentsByStatement. يمكنك إرسال تعليق إلى المشتري أثناء استخدام state A. لإجراء ذلك، عليك تعديل الحقل marketplaceComment في الاقتراح باستخدام updateProposals. سيتم إرسال التعليق بعد ذلك عند طلب موافقة المشتري.

تم الانتهاء

عندما توافق أنت والمشتري على اقتراح الإعلان الآلي، سيتم تدخل في حالة نهائية (state F في الشكل 1). ينشئ "مدير الإعلانات" بعد ذلك عناصر تلقائيًا من هذا الاقتراح الآلي.

في معظم الحالات، تكون قد انتهيت الآن من عرض الإعلان الآلي؛ ومع ذلك، هناك هما إجراءان يمكنك تنفيذهما من هذه الحالة:

• يمكنك إعادة فتح اقتراح الإعلان الآلي لإعادة التفاوض عن طريق تعديله ذات الصلة بعرض الإعلانات في العرض. يمكنك القيام بذلك عن طريق فتح اقتراح تعديل (state E to A في الشكل 1) وإجراء تغييرات، يطلب قبول المشتري.
• يمكنك إجراء تعديلات متعلّقة بعدم عرض الإعلانات، مثل تعديل الاقتراح. الاسم، ويعكس هذه التغييرات في الترتيب والعناصر التي تم إنشاؤها في "مدير إعلانات Google" من هذه الصفقة. ويمكنك إجراء ذلك عن طريق تعديل من state E في الشكل 1 ثم تنفيذ إجراء UpdateOrderWithSellerData.