Có lập trình

Hướng dẫn này là 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. Tài liệu này mô tả cách tạo Đề xuất và cách thực hiện thương lượng.

Primer

Đề xuất có lập trình tương tự như một đơn đặt hàng trong Google Ad Manager. Đề xuất có lập trình chứa nhiều thông tin về 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, đại diện cho lời đề nghị cung cấp khoảng không quảng cáo cho người mua.

Để biết thêm thông tin, hãy truy cập 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ã 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);
    

Xem trên 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(),
    # ...
}
    

Xem trên GitHub

1.199

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

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

Xem trên 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
    }
};
    

Xem trên GitHub

Ruby

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

Xem trên GitHub

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

Java

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

Xem trên GitHub

Python

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

Xem trên GitHub

1.199

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

Xem trên 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
};
    

Xem trên GitHub

Ruby

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

Xem trên GitHub

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 mới 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 ở nhiều điểm khác nhau trong quá trình thương lượng từ góc độ API. Mỗi trạng thái được biểu thị bằng nhiều tổ hợp trường sau đây:

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

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

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

Hướng dẫn từng bước về 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 thương lượng cho một đề xuất có lập trình với người mua. Chúng tôi sẽ tham chiếu các trạng thái trong sơ đồ ở trên.

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 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 đã sẵn sàng để người mua 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, có một số điều 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ần thay đổi.
• Người mua có thể đề xuất các thay đổi. Trong trường hợp này, đề xuất sẽ được gửi trở lại trạng thái bản nháp (state B trong Hình 1). Sau đó, bạn sẽ 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 đề xuất đó cho người mua xem xét.
• Bạn cũng có thể quyết định thực hiện các 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 ở Hình 1.

Lưu ý: Khi đề xuất có lập trình đang mở để chỉnh sửa (state A trong Hình 1), đề xuất đó sẽ không tự động nhận thông tin cập nhật từ Thị trường. Điều này có nghĩa là nếu người mua thực hiện thay đổi trước khi bạn yêu cầu người mua chấp nhận, thì bạn sẽ nhận được thông báo lỗi NEW_VERSION_FROM_BUYER vào khi cố yêu cầu người mua chấp nhận. Để khắc phục vấn đề này, hãy thực hiện thao tác DiscardProposalDrafts. Thao tác này sẽ ghi đè các nội dung chỉnh sửa cục bộ của bạn bằng những thay đổi mới nhất đối với người mua từ Trang web thương mại. Sau đó, bạn sẽ cần phải áp dụng lại các nội dung chỉnh sửa cho địa phương của mì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 nhận xét cho người mua trong state A. Để thực hiện việc này, bạn cần cập nhật trường marketplaceComment trong đề xuất bằng cách sử dụng tính năng updateProposals. Sau đó, nhận xét 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, thì đề xuất sẽ chuyển sang trạng thái hoàn tất (state F trong Hình 1). Sau đó, Ad Manager 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, hiện bạn đã hoàn tất đề xuất có lập trình; tuy nhiên, có 2 hành động bạn có thể thực hiện 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 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 chỉnh sửa liên quan đến việc không 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 Ad Manager và các mục hàng được tạo từ giao dịch 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, sau đó thực hiện thao tác UpdateOrderWithSellerData.