آلية

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

Primer

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

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

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

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

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)، لن يتلقّى هذا الاقتراح تلقائيًا أي أخبار من Marketplace. وهذا يعني أنه في حال أجرى المشتري تغييرًا قبل طلب قبول المشتري، ستتلقى رسالة الخطأ NEW_VERSION_FROM_BUYER عند محاولة طلب قبول المشتري. لحل هذه المشكلة، نفِّذ الإجراء DiscardProposalDrafts ، والذي سيؤدي إلى استبدال تعديلاتك المحلية بآخر التغييرات التي تم إجراؤها على المشترين من السوق. وسيكون عليك بعد ذلك إعادة تطبيق التعديلات المحلية.

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

تم الانتهاء

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

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

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