برنامه ای

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

آغازگر

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

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

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

برای ایجاد یک شیء Proposal ، فقط نام و خریدار برنامه‌ای مورد نیاز است. شناسه خریدار برنامه‌ای را می‌توان از طریق UI یا جدول 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);

پایتون


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

PHP


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

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

سی شارپ


// 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
    }
};

روبی


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

قبل از ارسال به خریدار برای مذاکره، فیلدهای اضافی باید تنظیم شوند. پیشنهاد باید دارای مخاطبین تبلیغ کننده، فروشنده، قاچاقچی و فروشنده باشد.

جاوا


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

پایتون


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

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

سی شارپ


// 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
};

روبی


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

از آنجایی که پروپوزال ها معمولاً از اشیاء ProposalLineItem تشکیل شده اند، گام بعدی اضافه کردن موارد خط پیشنهادی زیر پروپوزال جدید ایجاد شده شما خواهد بود.

وضعیت های یک پیشنهاد برنامه ای

شکل زیر یک پیشنهاد برنامه‌ریزی شده را در نقاط مختلف فرآیند مذاکره از دیدگاه API نشان می‌دهد. هر حالت با ترکیب های مختلفی از فیلدهای زیر نشان داده می شود:

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

حالت‌هایی که یک پیشنهاد برنامه‌ریزی شده می‌تواند در طول تعامل آن با Marketplace باشد.
شکل 1 : وضعیت های یک پیشنهاد برنامه ای

روند مذاکرات

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

آماده شدن برای بررسی یا پذیرش خریدار

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

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

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

مذاکره

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

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

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

نهایی شد

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

در بیشتر موارد شما اکنون با پیشنهاد برنامه‌ای تمام شده‌اید. با این حال، دو عمل وجود دارد که می توانید از این حالت انجام دهید:

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