Programmatisch

Dieser Leitfaden bietet einen allgemeinen Überblick über die Verwendung von Programmatic Direct-Funktionen über die API. Darin wird beschrieben, wie Sie ein Angebot erstellen und Verhandlungen führen.

Primer

Ein programmatisches Angebot ähnelt einem Auftrag in Google Ad Manager. Programmatische Angebote enthalten allgemeine Informationen zu einer vorgeschlagenen Transaktion zwischen Ihnen und einem Käufer. Ein Angebot mit seinen Werbebuchungen stellt ein Angebot von Inventar an 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 programmatische Käufer-ID kann über die Benutzeroberfläche 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);

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

Bevor Sie das Angebot zur Verhandlung an den Käufer senden, müssen zusätzliche Felder festgelegt werden. Das Angebot muss einen Werbetreibenden, einen Vertriebsmitarbeiter, einen Trafficker und Kontakte des Verkäufers enthalten.

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

Da Angebote in der Regel aus ProposalLineItem-Objekten bestehen, müssen Sie als Nächstes Angebotswerbebuchungen unter Ihrem neu erstellten Angebot hinzufügen.

Status eines programmatischen Angebots

Die folgende Abbildung zeigt ein programmatisches Angebot an verschiedenen Punkten des Verhandlungsprozesses aus API-Sicht. Jeder Status wird durch verschiedene Kombinationen der folgenden Felder dargestellt:

Weitere Informationen finden Sie in der Ad Manager-Hilfe.

Die Status, die ein programmatisches Angebot während der Interaktion mit dem Marktplatz haben kann.
Abbildung 1: Status eines programmatischen Angebots

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

In diesem Artikel wird beschrieben, wie Sie die API verwenden, um eine Verhandlung für ein programmatisches Angebot mit einem Käufer abzuschließen. Wir beziehen uns auf die Status im Diagramm oben.

Vorbereitung auf die Überprüfung oder Annahme durch den Käufer

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

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

Wenn Sie bereit sind, das programmatische Angebot vom Käufer überprüfen zu lassen, können Sie RequestBuyerReview oder RequestBuyerAcceptance mit der Methode ProposalService.performProposalAction verwenden. Damit gelangen Sie in die Verhandlungsphase.

Verhandlung

In dieser Phase kann Folgendes passieren:

  • Der Käufer kann Ihr programmatisches Angebot ohne Änderungen annehmen.
  • Der Käufer kann Änderungen vorschlagen. In diesem Fall wird das Angebot in den Entwurfsstatus zurückgesetzt (state B in Abbildung 1). Sie müssen dann das Angebot zum Bearbeiten öffnen, die vorgeschlagenen Änderungen vornehmen und es zur Überprüfung an den Käufer zurücksenden.
  • Sie können auch Änderungen vornehmen, bevor der Käufer antwortet. Dazu können Sie das Angebot in Abbildung 1 über state D zur Bearbeitung öffnen.

Diese Verhandlung wird fortgesetzt, bis Sie eine Einigung mit dem Käufer erzielen. Kommentare zwischen Ihnen und dem Käufer können mit getMarketplaceCommentsByStatement abgerufen werden. Sie können dem Käufer in state A einen Kommentar senden. Dazu müssen Sie das Feld marketplaceComment im Vorschlag mit updateProposals aktualisieren. 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 abgeschlossen (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 jetzt fertig. Es gibt jedoch zwei Aktionen, die Sie in diesem Status ausführen können:

  • Sie können das programmatische Angebot neu verhandeln, indem Sie die Felder im Angebot bearbeiten, die mit der Auslieferung zusammenhängen. Dazu öffnen Sie das Angebot zur Bearbeitung (state E to A in Abbildung 1), nehmen Änderungen vor und fordern dann die Annahme durch den Käufer an.
  • Sie können Änderungen vornehmen, die nicht mit der Anzeigenbereitstellung zusammenhängen, z. B. den Namen des Angebots aktualisieren. Diese Änderungen werden dann im Ad Manager-Auftrag und den Werbebuchungen, die aus diesem Deal erstellt wurden, berücksichtigt. Dazu bearbeiten Sie das state E in Abbildung 1 und führen dann die Aktion UpdateOrderWithSellerData aus.