Esta guía es una descripción general de alto nivel sobre el uso de funciones de Programática directa a través de la API. Describe cómo crear una propuesta y cómo realizar una negociación.
Primer
Una propuesta programática es similar a un pedido en Google Ad Manager. Las propuestas programáticas contienen información amplia sobre una transacción propuesta entre tú y un comprador. Una propuesta, junto con sus líneas de pedido, representa una oferta de inventario para un comprador.
Para obtener más información, consulte el Centro de ayuda.
Cómo crear una propuesta a través de la API
Para crear un objeto Proposal
, solo se requieren el nombre y el comprador programático. El ID del comprador programático se puede obtener a través de la IU o la tabla de PQL de 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);
Python
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);
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 } };
Ruby
# Create proposal configuration object. proposal = { :marketplace_info => { :buyer_account_id => buyer_id }, :name => 'Proposal %s' % SecureRandom.uuid(), # ... }
Antes de enviar al comprador para la negociación, se deben establecer campos adicionales. La propuesta debe tener contactos de anunciante, vendedor, coordinador de anuncios y vendedor.
Java
SalespersonSplit primarySalesperson = new SalespersonSplit(); primarySalesperson.setUserId(primarySalespersonId); proposal.setPrimarySalesperson(primarySalesperson);
Python
'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);
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 };
Ruby
:primary_salesperson => { :user_id => primary_salesperson_id }, :primary_trafficker_id => primary_trafficker_id
Dado que las propuestas generalmente están compuestas por objetos ProposalLineItem, el siguiente paso sería agregar líneas de pedido propuestas debajo de la propuesta recién creada.
Estados de una propuesta programática
En la siguiente figura, se muestra una propuesta programática en varios momentos del proceso de negociación desde el punto de vista de la API. Cada estado se representa con varias combinaciones de los siguientes campos:
- ProposalMarketplaceInfo.hasLocalVersionEdits
- ProposalMarketplaceInfo.negotiationStatus
- Proposal.status
Para obtener más información, consulta el Centro de ayuda de Ad Manager.
Explicación de la negociación
A continuación, te indicamos cómo usar la API para completar una negociación para una propuesta programática con un comprador. Haremos referencia a los estados en el diagrama anterior.
Cómo prepararse para la revisión o aceptación del comprador
Primero, debes crear un borrador de una propuesta programática con líneas de pedido propuestas que quieras enviar a un comprador. Es state C
en la figura anterior.
Solicitar la revisión o aceptación del comprador
Una vez que estés listo para que el comprador revise la propuesta programática, puedes RequestBuyerReview
o RequestBuyerAcceptance
con el método ProposalService.performProposalAction.
Esto te llevará a la fase de negociación.
Negociación
En esta fase, pueden ocurrir varias cosas.
- Es posible que el comprador acepte su propuesta programática sin realizar cambios.
- El comprador puede proponer cambios. En este caso, la propuesta se enviará de vuelta al estado de borrador (
state B
en la Figura 1). Luego, deberás abrir la propuesta para editarla, realizar los cambios propuestos y enviarla de vuelta para que la revise el comprador. - También puedes decidir realizar cambios incluso antes de que el comprador responda. Puedes hacerlo abriendo la propuesta para editar desde
state D
en la Figura 1.
Esta negociación continúa hasta que llega a un acuerdo con el comprador. Los comentarios entre tú y el comprador se pueden recuperar con getMarketplaceCommentsByStatement.
Puedes enviarle un comentario al comprador desde state A
. Para
hacer esto, deberás actualizar el
campo marketplaceComment
en la propuesta mediante
updateProposals.
El comentario se enviará cuando solicites la aceptación del comprador.
Finalizada
Cuando tanto tú como el comprador hayan aceptado la propuesta programática, esta entra en el estado finalizado (state F
en la Figura 1).
Luego, Ad Manager crea automáticamente líneas de pedido a partir de esta propuesta programática.
En la mayoría de los casos, ya terminaste con la propuesta programática. Sin embargo, hay dos acciones que puedes realizar desde este estado:
- Puedes reabrir la propuesta programática para su renegociación; para ello, edita los campos relacionados con la entrega en la propuesta. Puedes hacerlo abriendo la propuesta para editarla (
state E to A
en la Figura 1), realizando cambios y, luego, solicitando la aceptación del comprador. - Puedes realizar ediciones no relacionadas con la publicación, como actualizar el nombre de la propuesta y reflejar estos cambios en el pedido de Ad Manager y las líneas de pedido creadas a partir de este acuerdo. Para ello, edita desde
state E
en la Figura 1 y, luego, realiza la acciónUpdateOrderWithSellerData
.