Có lập trình

Hướng dẫn này cung cấp thông tin tổng quan ở cấp cao về cách sử dụng các tính năng Trực tiếp theo chương trình thông qua API. Phần này mô tả cách tạo Đề xuất và cách thực hiện đàm phán.

Primer

Đề xuất có lập trình tương tự như đơn đặt hàng trong Google Ad Manager. Đề xuất có lập trình chứa thông tin chung về một giao dịch được đề xuất giữa bạn và người mua. Đề xuất, cùng với các mục hàng, thể hiện một đề nghị về khoảng không quảng cáo cho người mua.

Để biết thêm thông tin, hãy truy cập vào Trung tâm trợ giúp.

Tạo đề xuất thông qua API

Để tạo đối tượng Proposal, bạn chỉ cần có tên và người mua có lập trình. Bạn có thể lấy mã nhận dạng người mua có lập trình thông qua giao diện người dùng hoặc bảng 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);

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

Bạn cần phải đặt các trường bổ sung trước khi gửi cho người mua để thương lượng. Đề xuất phải có nhà quảng cáo, người bán hàng, người quản lý quảng cáo và thông tin liên hệ của người bán.

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

Vì đề xuất thường bao gồm các đối tượng ProposalLineItem, nên bước tiếp theo là thêm các mục hàng đề xuất bên dưới đề xuất bạn vừa tạo.

Trạng thái của đề xuất có lập trình

Hình sau đây mô tả một đề xuất có lập trình tại nhiều thời điểm trong quy trình thương lượng theo quan điểm của API. Mỗi trạng thái được biểu thị bằng nhiều tổ hợp của các trường sau:

Để biết thêm thông tin, hãy truy cập Trung tâm trợ giúp của Ad Manager.

Các trạng thái mà một đề xuất có lập trình có thể có trong quá trình tương tác với Marketplace.
Hình 1: Các trạng thái của đề xuất có lập trình

Hướng dẫn thương lượng

Tại đây, chúng tôi sẽ hướng dẫn bạn cách sử dụng API để hoàn tất quy trình thương lượng cho một đề xuất có lập trình với người mua. Chúng ta sẽ tham chiếu các trạng thái trong sơ đồ ở trên.

Đang chuẩn bị để người mua xem xét hoặc chấp nhận

Trước tiên, bạn cần soạn thảo một đề xuất có lập trình với các mục hàng đề xuất mà bạn muốn gửi cho người mua. Đây là state C trong hình trên.

Yêu cầu người mua xem xét hoặc chấp nhận

Khi người mua đã sẵn sàng xem xét đề xuất có lập trình, bạn có thể RequestBuyerReview hoặc RequestBuyerAcceptance bằng cách sử dụng phương thức ProposalService.performProposalAction. Thao tác này sẽ đưa bạn vào giai đoạn thương lượng.

Thương lượng

Trong giai đoạn này, một số việc có thể xảy ra.

  • Người mua có thể chấp nhận đề xuất có lập trình của bạn mà không có thay đổi.
  • Người mua có thể đề xuất thay đổi. Trong trường hợp này, đề xuất sẽ được gửi lại về trạng thái nháp (state B trong Hình 1). Sau đó, bạn cần mở đề xuất để chỉnh sửa, thực hiện các thay đổi được đề xuất và gửi lại để người mua xem xét.
  • Bạn cũng có thể quyết định thực hiện thay đổi ngay cả trước khi người mua trả lời. Bạn có thể thực hiện việc này bằng cách mở đề xuất để chỉnh sửa từ state D trong Hình 1.

Quá trình thương lượng này sẽ tiếp tục cho đến khi bạn đạt được thoả thuận với người mua. Bạn có thể truy xuất bình luận giữa bạn và người mua bằng cách sử dụng getMarketplaceCommentsByStatement. Bạn có thể gửi bình luận cho người mua trong state A. Để thực hiện việc này, bạn sẽ cần cập nhật trường marketplaceComment trên đề xuất bằng cách sử dụng updateProposals. Sau đó, bình luận sẽ được gửi khi bạn yêu cầu người mua chấp nhận.

Đã hoàn thiện

Khi cả bạn và người mua đều đã chấp nhận đề xuất có lập trình, đề xuất đó sẽ chuyển sang trạng thái hoàn tất (state F trong Hình 1). Sau đó, Ad Manager sẽ tự động tạo các mục hàng từ đề xuất có lập trình này.

Trong hầu hết các trường hợp, bạn đã hoàn tất đề xuất có lập trình; tuy nhiên, bạn có thể thực hiện hai hành động từ trạng thái này:

  • Bạn có thể mở lại đề xuất có lập trình để thương lượng lại bằng cách chỉnh sửa các trường liên quan đến việc phân phát trên đề xuất. Bạn có thể thực hiện việc này bằng cách mở đề xuất để chỉnh sửa (state E to A trong Hình 1), thực hiện các thay đổi rồi yêu cầu người mua chấp nhận.
  • Bạn có thể thực hiện các nội dung chỉnh sửa không liên quan đến việc phân phát, chẳng hạn như cập nhật tên của đề xuất và phản ánh những thay đổi này trong đơn đặt hàng và mục hàng của Ad Manager được tạo từ thoả thuận này. Bạn thực hiện việc này bằng cách chỉnh sửa từ state E trong Hình 1, rồi thực hiện thao tác UpdateOrderWithSellerData.