برنامه‌ریزی‌شده

این راهنما مروری کلی بر نحوه استفاده از ویژگی‌های مستقیم برنامه‌ای ازطریق میانای برنامه‌سازی کاربردی است. این مقاله نحوه ایجاد «پیشنهاد» و نحوه انجام مذاکره را شرح می‌دهد.

Primer

پیشنهاد برنامه‌ای مشابه سفارش در Google Ad Manager است. پیشنهادهای برنامه‌ای حاوی اطلاعات کلی درباره تراکنش پیشنهادی بین شما و خریدار است. پیشنهاد، همراه با موارد سطری آن، نشان‌دهنده پیشنهاد موجودی به خریدار است.

برای اطلاعات بیشتر، به مرکز راهنمایی مراجعه کنید.

ایجاد پیشنهاد ازطریق API

برای ایجاد شیء 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

برای اطلاعات بیشتر، به مرکز راهنمایی Ad Manager مراجعه کنید.

شکل ۱: وضعیت‌های پیشنهاد برنامه‌ای

راهنمای گام‌به‌گام مذاکره

در اینجا، شما را در استفاده از API برای تکمیل مذاکره برای یک پیشنهاد برنامه‌ای با خریدار راهنمایی می‌کنیم. به حالت‌های موجود در نمودار بالا ارجاع خواهیم داد.

درحال آماده‌سازی برای مرور یا پذیرش خریدار

ابتدا باید پیش‌نویس پیشنهاد برنامه‌ای را با ردیف‌های پیشنهادی که می‌خواهید برای خریدار ارسال کنید تهیه کنید. این state C در شکل بالا است.

درخواست بازبینی یا پذیرش خریدار

وقتی آماده بودید که خریدار پیشنهاد برنامه‌ای را بازبینی کند، می‌توانید RequestBuyerReview یا RequestBuyerAcceptance را بااستفاده از روش ProposalService.performProposalAction انجام دهید. با این کار وارد مرحله مذاکره می‌شوید.

مذاکره

در این مرحله، ممکن است چند اتفاق بیفتد.

• خریدار ممکن است پیشنهاد برنامه‌ای شما را بدون تغییر بپذیرد.
• خریدار ممکن است تغییراتی را پیشنهاد دهد. در این حالت، پیشنهاد به حالت پیش‌نویس برگردانده می‌شود (state B در شکل ۱). سپس باید پیشنهاد را برای ویرایش باز کنید، تغییرات پیشنهادی را اعمال کنید، و آن را برای بازبینی خریدار برگردانید.
• همچنین می‌توانید تصمیم بگیرید که حتی قبل‌از پاسخ خریدار تغییراتی ایجاد کنید. می‌توانید این کار را با باز کردن پیشنهاد برای ویرایش از state D در شکل ۱ انجام دهید.

توجه: وقتی پیشنهاد برنامه‌ای برای ویرایش باز است (state A در شکل ۱)، به‌طور خودکار به‌روزرسانی‌ها را از Marketplace دریافت نخواهد کرد. این یعنی اگر خریدار قبل‌از اینکه شما درخواست پذیرش خریدار را بدهید تغییری ایجاد کند، هنگام تلاش برای درخواست پذیرش خریدار، پیام خطای NEW_VERSION_FROM_BUYER را دریافت خواهید کرد. برای رفع این مشکل، کنش DiscardProposalDrafts را انجام دهید، که ویرایش‌های محلی شما را با جدیدترین تغییرات خریدار از «بازار» بازنویسی می‌کند. سپس باید ویرایش‌های محلی‌تان را دوباره اعمال کنید.

این مذاکره تا زمانی که با خریدار به توافق برسید ادامه می‌یابد. نظرات بین شما و خریدار را می‌توان بااستفاده از getMarketplaceCommentsByStatement بازیابی کرد. وقتی در state A هستید، می‌توانید برای خریدار نظر ارسال کنید. برای انجام این کار، باید فیلد marketplaceComment را در پیشنهاد بااستفاده از updateProposals به‌روز کنید. سپس وقتی درخواست پذیرش خریدار را می‌دهید، نظر ارسال می‌شود.

نهایی‌شده

وقتی هم شما و هم خریدار پیشنهاد برنامه‌ای را پذیرفتید، به حالت نهایی‌شده می‌رود (state F در شکل ۱). سپس Ad Manager به‌طور خودکار از این پیشنهاد برنامه‌ای، مورد خطی ایجاد می‌کند.

در بیشتر موارد، کارتان با پیشنهاد برنامه‌ای تمام شده است؛ اما دو کنش وجود دارد که می‌توانید از این وضعیت انجام دهید:

• می‌توانید پیشنهاد برنامه‌ای را برای مذاکره مجدد با ویرایش فیلدهای مربوط به ارائه در پیشنهاد دوباره باز کنید. می‌توانید این کار را با باز کردن پیشنهاد برای ویرایش (state E to A در شکل ۱)، ایجاد تغییرات، و سپس درخواست پذیرش خریدار انجام دهید.
• می‌توانید ویرایش‌های غیرمرتبط با ارائه را انجام دهید، مانند به‌روزرسانی نام پیشنهاد، و این تغییرات را در سفارش Ad Manager و موارد خطی ایجادشده از این معامله منعکس کنید. این کار را با ویرایش کردن state E در شکل ۱ و سپس انجام دادن کنش UpdateOrderWithSellerData انجام می‌دهید.