Terprogram

Panduan ini adalah ringkasan tingkat tinggi tentang cara menggunakan fitur Langsung Terprogram melalui API. Panduan ini menjelaskan cara membuat Proposal dan cara melakukan negosiasi.

Primer

Proposal terprogram mirip dengan pesanan di Google Ad Manager. Proposal terprogram berisi informasi umum tentang transaksi yang diusulkan antara Anda dan pembeli. Proposal, bersama dengan item barisnya, mewakili penawaran inventaris kepada pembeli.

Untuk informasi selengkapnya, lihat Pusat Bantuan.

Membuat proposal melalui API

Untuk membuat objek Proposal, hanya nama dan pembeli terprogram yang diperlukan. ID pembeli terprogram dapat diperoleh melalui UI atau tabel 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);
    

Lihat di 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(),
    # ...
}
    

Lihat di GitHub

PHP

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

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

Lihat di 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
    }
};
    

Lihat di GitHub

Ruby

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

Lihat di GitHub

Sebelum mengirim ke pembeli untuk negosiasi, kolom tambahan harus ditetapkan. Proposal harus memiliki pengiklan, staf penjualan, pemroses iklan, dan kontak penjual.

Java

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

Lihat di GitHub

Python

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

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

Lihat di 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
};
    

Lihat di GitHub

Ruby

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

Lihat di GitHub

Karena proposal umumnya terdiri dari objek ProposalLineItem, langkah berikutnya adalah menambahkan item baris proposal di bawah proposal yang baru Anda buat.

Status proposal terprogram

Gambar berikut menggambarkan proposal terprogram di berbagai titik selama proses negosiasi dari sudut pandang API. Setiap status diwakili oleh berbagai kombinasi kolom berikut:

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

Untuk informasi selengkapnya, lihat Pusat Bantuan Ad Manager.

Gambar 1: Status proposal terprogram

Panduan negosiasi

Di sini, kami akan memandu Anda menggunakan API untuk menyelesaikan negosiasi proposal terprogram dengan pembeli. Kita akan merujuk ke status dalam diagram di atas.

Mempersiapkan peninjauan atau penerimaan pembeli

Pertama, Anda harus membuat draf proposal terprogram dengan item baris proposal yang ingin Anda kirimkan kepada pembeli. Ini adalah state C pada gambar di atas.

Meminta peninjauan atau persetujuan pembeli

Setelah Anda siap meminta pembeli meninjau proposal terprogram, Anda dapat RequestBuyerReview atau RequestBuyerAcceptance menggunakan metode ProposalService.performProposalAction. Tindakan ini akan membawa Anda ke fase negosiasi.

Negosiasi

Pada fase ini, sejumlah hal dapat terjadi.

• Pembeli dapat menerima proposal terprogram Anda tanpa perubahan.
• Pembeli dapat mengusulkan perubahan. Dalam hal ini, proposal akan dikirim kembali ke status draf (state B pada Gambar 1). Kemudian, Anda harus membuka proposal untuk diedit, melakukan perubahan yang diusulkan, dan mengirimkannya kembali untuk ditinjau pembeli.
• Anda juga dapat memutuskan untuk melakukan perubahan bahkan sebelum pembeli membalas. Anda dapat melakukannya dengan membuka proposal untuk diedit dari state D di Gambar 1.

Catatan: Saat proposal terprogram terbuka untuk diedit (state A di Gambar 1), proposal tersebut tidak akan otomatis menerima update dari Marketplace. Artinya, jika pembeli melakukan perubahan sebelum Anda meminta persetujuan pembeli, Anda akan menerima pesan error NEW_VERSION_FROM_BUYER saat mencoba meminta persetujuan pembeli. Untuk memperbaikinya, lakukan tindakan DiscardProposalDrafts, yang akan menimpa hasil edit lokal Anda dengan perubahan pembeli terbaru dari Marketplace. Kemudian, Anda harus menerapkan ulang hasil edit lokal.

Negosiasi ini berlanjut hingga Anda mencapai kesepakatan dengan pembeli. Komentar antara Anda dan pembeli dapat diambil menggunakan getMarketplaceCommentsByStatement. Anda dapat mengirim komentar kepada pembeli saat berada di state A. Untuk melakukannya, Anda harus memperbarui kolom marketplaceComment pada proposal menggunakan updateProposals. Komentar tersebut kemudian akan dikirim saat Anda meminta persetujuan pembeli.

Diselesaikan

Setelah Anda dan pembeli menyetujui proposal terprogram, proposal tersebut akan masuk ke status selesai (state F pada Gambar 1). Kemudian, Ad Manager akan otomatis membuat item baris dari proposal terprogram ini.

Pada umumnya, Anda kini telah selesai dengan proposal terprogram; namun, ada dua tindakan yang dapat Anda lakukan dari status ini:

• Anda dapat membuka kembali proposal terprogram untuk negosiasi ulang dengan mengedit kolom terkait penayangan di proposal. Anda dapat melakukannya dengan membuka proposal untuk diedit (state E to A di Gambar 1), melakukan perubahan, lalu meminta persetujuan pembeli.
• Anda dapat melakukan pengeditan yang tidak terkait dengan penayangan, seperti memperbarui nama proposal, dan menerapkan perubahan ini dalam pesanan dan item baris Ad Manager yang dibuat dari transaksi ini. Anda dapat melakukannya dengan mengedit dari state E di Gambar 1, lalu melakukan tindakan UpdateOrderWithSellerData.