Có lập trình

Hướng dẫn này cung cấp thông tin tổng quan về cách sử dụ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 cũng tương tự như một đơn đặt hàng trong Google Ad Manager. Đề xuất có lập trình chứa thông tin rộng về giao dịch được đề xuất giữa bạn và người mua. Một đề xuất cùng với các mục hàng của nó, đại diện cho việc cung cấp khoảng không quảng cáo cho người mua.

Để biết thêm thông tin, hãy tham khảo Trung tâm trợ giúp.

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

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

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

PHP

$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 thiết lập các trường bổ sung. Đề xuất phải có thông tin liên hệ của nhà quảng cáo, nhân viên bán hàng, nhà quản lý quảng cáo và 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

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

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 ProposalLineItem thì bước tiếp theo là thêm mục hàng đề xuất bên dưới đã tạo đề xuất.

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

Hình dưới đây mô tả một đề xuất có lập trình tại nhiều thời điểm trong thời gian quá trình thương lượng trên quan điểm API. Mỗi trạng thái được biểu thị bằng các 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 một đề xuất có lập trình

Hướng dẫn từng bước về việc thương lượng

Dưới đây, chúng tôi sẽ hướng dẫn bạn sử dụng API để hoàn tất thương lượng cho với người mua. Chúng ta sẽ tham chiếu các trạng thái trong biểu đồ ở trên.

Chuẩn bị cho việc xem xét hoặc chấp nhận của người mua

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 pháp ProposalService.performProposalAction. Bước này sẽ chuyển bạn sang giai đoạn thương lượng.

Thương lượng

Trong giai đoạn này, 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 thay đổi. Trong trường hợp này, đề xuất sẽ được gửi lại sang 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ể làm điều này bằng cách mở đề xuất để chỉnh sửa từ state D trong Hình 1.

Lưu ý: Khi đề xuất có lập trình được mở để chỉnh sửa (state A trong Hình 1), ứng dụng sẽ không tự động nhận thông tin cập nhật từ Marketplace. Đ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 khi thử 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 hành động DiscardProposalDrafts, Thao tác này sẽ ghi đè các chỉnh sửa cục bộ của bạn bằng những thay đổi mới nhất của người mua từ Thị trường. Sau đó, bạn sẽ cần phải áp dụng lại các nội dung chỉnh sửa của địa phương.

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ình luận giữa bạn và người mua có thể được truy xuất 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. Việc cần làm điều này, bạn sẽ cần phải cập nhật marketplaceComment trên đề xuất bằng cách sử dụng updateProposals. Sau đó, nhận xét này 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, chuyển sang trạng thái hoàn tất (state F trong Hình 1). Sau đó, Ad Manager tự động tạo 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 hiện đã hoàn thành đề xuất có lập trình; tuy nhiên, ở đó là hai hành động mà 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 phân phát trong đề 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 và sau đó 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 và phản ánh những thay đổi này trong đơn đặt hàng Ad Manager và các mục hàng đã tạo khỏi giao dịch này. Bạn làm việc này bằng cách chỉnh sửa state E trong Hình 1 rồi thực hiện thao tác UpdateOrderWithSellerData.