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 luas tentang transaksi yang diusulkan antara Anda dan pembeli. Proposal, bersama dengan item barisnya, mewakili penawaran inventaris kepada pembeli.

Untuk mengetahui 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 kontak pengiklan, staf penjualan, pemroses iklan, dan 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 selanjutnya adalah menambahkan item baris proposal di bawah proposal yang baru dibuat.

Status proposal terprogram

Gambar berikut menggambarkan proposal terprogram pada 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 status dalam diagram di atas.

Menyiapkan peninjauan atau persetujuan pembeli

Pertama, Anda harus membuat draf proposal terprogram dengan item baris proposal yang ingin Anda kirim ke pembeli. Ini adalah state C dalam gambar di atas.

Meminta peninjauan atau persetujuan pembeli

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

Negosiasi

Pada fase ini, sejumlah hal mungkin terjadi.

• Pembeli dapat menyetujui proposal terprogram Anda tanpa perubahan.
• Pembeli dapat mengusulkan perubahan. Dalam hal ini, proposal akan dikirim kembali ke status draf (state B di Gambar 1). Kemudian, Anda harus membuka proposal untuk diedit, melakukan perubahan yang diusulkan, lalu 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: Jika proposal terprogram dapat diedit (state A pada 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 memperbaiki masalah ini, jalankan tindakan DiscardProposalDrafts, yang akan menimpa hasil edit lokal Anda dengan perubahan pembeli terbaru dari Marketplace. Kemudian, Anda perlu menerapkan kembali 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

Jika Anda dan pembeli telah menyetujui proposal terprogram, proposal akan berstatus final (state F pada Gambar 1). Kemudian, Ad Manager akan otomatis membuat item baris dari proposal terprogram ini.

Dalam sebagian besar kasus, Anda kini selesai dengan proposal terprogram; tetapi, ada dua tindakan yang dapat dilakukan dari status ini:

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