이 페이지는 Cloud Translation API를 통해 번역되었습니다.

프로그래매틱

이 가이드에서는 API를 통해 프로그래매틱 다이렉트 기능을 사용하는 방법을 개략적으로 설명합니다. 제안서를 만들고 협상을 수행하는 방법을 설명합니다.

Primer

프로그래매틱 제안서는 Google Ad Manager의 주문과 유사합니다. 프로그래매틱 제안서에는 게시자와 구매자 사이의 제안된 거래에 관한 광범위한 정보가 포함됩니다. 제안서는 광고 항목과 함께 구매자에게 제공되는 인벤토리 제안을 나타냅니다.

자세한 내용은 고객센터를 참고하세요.

API를 통해 제안서 만들기

Proposal 객체를 만들려면 이름과 프로그래매틱 구매자만 필요합니다. 프로그래매틱 구매자 ID는 UI 또는 Programmatic_Buyer PQL 테이블을 통해 가져올 수 있습니다.

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

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

GitHub에서 보기

PHP


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

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

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

GitHub에서 보기

Ruby


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

GitHub에서 보기

협상을 위해 구매자에게 전송하기 전에 추가 입력란을 설정해야 합니다. 제안서에는 광고주, 영업 담당자, 애드 마스터, 판매자 연락처가 있어야 합니다.

Java


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

GitHub에서 보기

Python


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

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

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

GitHub에서 보기

Ruby


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

GitHub에서 보기

제안서는 일반적으로 ProposalLineItem 객체로 구성되므로 다음 단계는 새로 만든 제안서 아래에 제안서 광고 항목을 추가하는 것입니다.

프로그래매틱 제안서 상태

다음 그림은 API 관점에서 협상 과정 중 다양한 시점에서 프로그래매틱 제안서를 보여줍니다. 각 상태는 다음 필드의 다양한 조합으로 표현됩니다.

자세한 내용은 Ad Manager 고객센터를 참조하세요.

프로그래매틱 제안서가 Marketplace와 상호작용하는 동안 있을 수 있는 상태입니다. — **그림 1**: 프로그래매틱 제안서의 상태

협상 둘러보기

이제 API를 사용하여 구매자와 프로그래매틱 제안서 협상을 완료하는 방법을 알아보겠습니다. 위 다이어그램의 상태를 참조하겠습니다.

구매자 검토 또는 승인 준비 중

먼저 구매자에게 보낼 제안서 광고 항목이 포함된 프로그래매틱 제안서 초안을 작성해야 합니다. 위 그림에서 state C입니다.

구매자 검토 또는 승인 요청

구매자가 프로그래매틱 제안서를 검토하도록 할 준비가 되면 ProposalService.performProposalAction 메서드를 사용하여 RequestBuyerReview 또는 RequestBuyerAcceptance를 진행할 수 있습니다. 이렇게 하면 협상 단계로 넘어갑니다.

협상

이 단계에서는 다양한 상황이 발생할 수 있습니다.

구매자는 프로그래매틱 제안서를 변경하지 않고 수락할 수 있습니다.
구매자가 변경사항을 제안할 수 있습니다. 이 경우 제안서는 초안 상태로 다시 전송됩니다 (그림 1의 state B). 그런 다음 수정을 위해 제안서를 열고, 제안된 변경사항을 적용한 후 구매자의 검토를 위해 다시 전송해야 합니다.
구매자가 답변하기 전에도 변경할 수 있습니다. 그림 1의 state D에서 수정할 제안서를 열면 됩니다.

이 협상은 구매자와 합의할 때까지 계속됩니다. 개발자와 구매자 간의 주석은 getMarketplaceCommentsByStatement를 사용하여 검색할 수 있습니다. state A에서 구매자에게 의견을 보낼 수 있습니다. 이렇게 하려면 updateProposals를 사용하여 제안서의 marketplaceComment 필드를 업데이트해야 합니다. 그러면 구매자 승인을 요청할 때 의견이 전송됩니다.

확정됨

게시자와 구매자가 모두 프로그래매틱 제안서를 수락하면 제안서는 최종 상태가 됩니다 (그림 1의 state F). 그런 다음 Ad Manager는 이 프로그래매틱 제안서에서 광고 항목을 자동으로 생성합니다.

이제 대부분의 경우 프로그래매틱 제안서는 사용할 수 없습니다. 하지만 이 상태에서 실행할 수 있는 작업은 두 가지입니다.

제안서에서 게재 관련 필드를 수정하여 재협상을 위해 프로그래매틱 제안서를 다시 열 수 있습니다. 이렇게 하려면 수정할 제안서를 열고 (그림 1의 state E to A) 변경한 다음 구매자 승인을 요청하면 됩니다.
제안서의 이름을 업데이트하거나 이 거래를 통해 생성된 Ad Manager 주문과 광고 항목에 변경사항을 반영하는 등 미게재 관련 수정을 할 수 있습니다. 그림 1의 state E에서 UpdateOrderWithSellerData 작업을 실행하면 됩니다.