آلية

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

Primer

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

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

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

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

جافا

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

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

جافا

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

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

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

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

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

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

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

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

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

التفاوض

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

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

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

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

تم الانتهاء

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

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

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