Programmatic

In dieser Anleitung erhalten Sie einen allgemeinen Überblick darüber, wie Sie die Funktionen von Programmatic Direct über die API verwenden. Darin wird beschrieben, wie ein Angebot erstellt und eine Verhandlung durchgeführt wird.

Primer

Ein programmatisches Angebot ähnelt einem Auftrag in Google Ad Manager. Programmatische Angebote enthalten umfassende Informationen zu einer vorgeschlagenen Transaktion zwischen Ihnen und einem Käufer. Ein Angebot stellt zusammen mit seinen Werbebuchungen ein Inventarangebot für einen Käufer dar.

Weitere Informationen finden Sie in der Hilfe.

Angebot über die API erstellen

Zum Erstellen eines Proposal-Objekts sind nur der Name und der programmatische Käufer erforderlich. Die ID des programmatischen Käufers kann über die UI oder die PQL-Tabelle Programmatic_Buyer abgerufen werden.

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

Auf GitHub ansehen

Python

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

Auf GitHub ansehen

PHP

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

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

Auf GitHub ansehen

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

Auf GitHub ansehen

Ruby

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

Auf GitHub ansehen

Bevor Sie das Formular zur Verhandlung an den Käufer senden, müssen zusätzliche Felder festgelegt werden. Das Angebot muss einen Werbetreibenden, einen Verkäufer, einen Trafficker und einen Verkäuferkontakt haben.

Java

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

Auf GitHub ansehen

Python

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

Auf GitHub ansehen

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

Auf GitHub ansehen

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

Auf GitHub ansehen

Ruby

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

Auf GitHub ansehen

Da Angebote im Allgemeinen aus ProposalLineItem-Objekten bestehen, besteht der nächste Schritt darin, Angebotswerbebuchungen unter dem neu erstellten Angebot hinzuzufügen.

Status eines programmatischen Angebots

Die folgende Abbildung zeigt ein programmatisches Angebot an verschiedenen Stellen während des Verhandlungsprozesses aus Sicht der API. Jeder Zustand wird durch verschiedene Kombinationen der folgenden Felder dargestellt:

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

Weitere Informationen finden Sie in der Ad Manager-Hilfe.

Abbildung 1: Status eines programmatischen Angebots

Schritt-für-Schritt-Anleitung für Verhandlungen

Im Folgenden wird beschrieben, wie Sie mithilfe der API eine Verhandlung mit einem Käufer über ein programmatisches Angebot abschließen. Wir verweisen auf die Zustände im Diagramm oben.

Überprüfung oder Annahme durch den Käufer vorbereiten

Zuerst müssen Sie ein programmatisches Angebot mit Angebotswerbebuchungen entwerfen, die Sie an einen Käufer senden möchten. Dies ist in der Abbildung oben state C.

Überprüfung oder Annahme durch den Käufer anfordern

Sobald der Käufer das programmatische Angebot prüfen soll, können Sie mit der Methode ProposalService.performProposalAction RequestBuyerReview oder RequestBuyerAcceptance ausführen. Dadurch gelangen Sie in die Verhandlungsphase.

Verhandlung

In dieser Phase kann eine Reihe von Dingen passieren.

• Der Käufer kann das programmatische Angebot ohne Änderungen akzeptieren.
• Der Käufer kann Änderungen vorschlagen. In diesem Fall wird das Angebot wieder in den Entwurfsstatus zurückversetzt (state B in Abbildung 1). Sie müssen dann das Angebot zur Bearbeitung öffnen, die vorgeschlagenen Änderungen vornehmen und das Angebot zur Überprüfung an den Käufer zurücksenden.
• Es ist auch möglich, Änderungen vorzunehmen, noch bevor der Käufer antwortet. Öffnen Sie dazu den Bearbeitungsvorschlag von state D in Abbildung 1.

Hinweis: Wenn ein programmatisches Angebot zur Bearbeitung geöffnet ist (state A in Abbildung 1), erhält es nicht automatisch Aktualisierungen vom Marketplace. Wenn also der Käufer eine Änderung vornimmt, bevor Sie die Annahme durch den Käufer anfordern, wird beim Versuch, die Annahme durch den Käufer anzufordern, die Fehlermeldung NEW_VERSION_FROM_BUYER angezeigt. Um dieses Problem zu beheben, führen Sie die Aktion DiscardProposalDrafts aus. Dadurch werden Ihre lokalen Änderungen mit den neuesten Käuferänderungen aus dem Marktplatz überschrieben. Anschließend müssen Sie die lokalen Änderungen noch einmal anwenden.

Diese Verhandlung wird fortgesetzt, bis Sie sich mit dem Käufer einigen. Kommentare zwischen Ihnen und dem Käufer können mit getMarketplaceCommentsByStatement abgerufen werden. Sie können in state A einen Kommentar an den Käufer senden. Aktualisieren Sie dazu das Feld marketplaceComment für das Angebot mit updateProposals. Der Kommentar wird dann gesendet, wenn Sie die Annahme durch den Käufer anfordern.

Abgeschlossen

Wenn sowohl Sie als auch der Käufer das programmatische Angebot angenommen haben, wird es in den Status „Abgeschlossen“ versetzt (state F in Abbildung 1). In Ad Manager werden dann automatisch Werbebuchungen aus diesem programmatischen Angebot erstellt.

In den meisten Fällen ist das programmatische Angebot nun fertig. Allerdings können Sie in diesem Status zwei Aktionen ausführen:

• Sie können das programmatische Angebot zur erneuten Verhandlung öffnen, indem Sie die zur Auslieferung bezogenen Felder im Angebot bearbeiten. Öffnen Sie dazu das Angebot zur Bearbeitung (state E to A in Abbildung 1), nehmen Sie Änderungen vor und fordern Sie dann die Annahme durch den Käufer an.
• Sie können Änderungen vornehmen, die sich nicht auf die Auslieferung beziehen, z. B. den Namen des Angebots aktualisieren und diese Änderungen im Ad Manager-Auftrag und in den Werbebuchungen berücksichtigen, die aus diesem Deal erstellt wurden. Dazu bearbeiten Sie den Wert von state E in Abbildung 1 und führen dann die Aktion UpdateOrderWithSellerData aus.