本指南阐述了提案订单项的定义,并逐步介绍了如何通过 API 创建 ProposalLineItem 对象。此外,本指南还介绍了必填字段,并探讨了当您在 Proposal 对象下创建提案订单项后可执行的后续步骤。
基础入门
什么是提案订单项?在 DFP 销售管理系统界面中,您会看到 Product 对象的目录,这些对象代表允许使用的定义或预设定义的通用模板,以方便定位。这些对象已经与 RateCard 对象配对,后者允许将 PremiumRate 对象应用于定价。当您填充其他必填的结算字段和投放字段时,您实际上是在创建 ProposalLineItem
对象(嵌套在 Proposal
对象下),代表 DFP 广告管理系统(以下简称 DFP)内尚未进入广告投放管理阶段的订单项对象。
通过 API 创建提案订单项
要在 API 中创建提案订单项,您必须拥有以下对象:
- 作为此提案订单项的关联对象的
Proposal
- 作为此提案订单项的定价依据的
RateCard
- 作为基础的
Product
请先在本地创建一个 ProposalLineItem
对象并为其分配名称。
Java
// Get the ProposalLineItemService. ProposalLineItemServiceInterface proposalLineItemService = dfpServices.get(session, ProposalLineItemServiceInterface.class); // Create a proposal line item. ProposalLineItem proposalLineItem = new ProposalLineItem(); proposalLineItem.setName("Proposal line item #" + new Random().nextInt(Integer.MAX_VALUE));
Python
# Initialize appropriate service. proposal_line_item_service = client.GetService( 'ProposalLineItemService', version='v201711') # Create a single proposal line item. proposal_line_item = { 'name': 'Proposal line item #%s' % uuid.uuid4(), ...
PHP
$proposalLineItemService = $dfpServices->get($session, ProposalLineItemService::class); // Create a standard proposal line item. $proposalLineItem = new ProposalLineItem(); $proposalLineItem->setName('Proposal line item #' . uniqid()); $proposalLineItem->setLineItemType(LineItemType::STANDARD);
C#
using (ProposalLineItemService proposalLineItemService = (ProposalLineItemService) user.GetService(DfpService.v201711.ProposalLineItemService)) // Create a proposal line item. ProposalLineItem proposalLineItem = new ProposalLineItem(); proposalLineItem.name = "Proposal line item #" + new Random().Next(int.MaxValue);
在本地创建此提案订单项后,您便可以将其与您的提案相关联,并分别设置沿用其定位和定价的产品和价目表。
Java
proposalLineItem.setProposalId(proposalId); proposalLineItem.setRateCardId(rateCardId); proposalLineItem.setProductId(productId); proposalLineItem.setTargeting(targeting);
Python
... 'rateCardId': rate_card_id, 'productId': product_id, 'proposalId': proposal_id, ...
PHP
$proposalLineItem->setProposalId($proposalId); $proposalLineItem->setRateCardId($rateCardId); $proposalLineItem->setProductId($productId);
C#
proposalLineItem.proposalId = proposalId; proposalLineItem.rateCardId = rateCardId; proposalLineItem.productId = productId; proposalLineItem.targeting = targeting;
提案订单项支持定位字段,其方式与 LineItem 对象一样。同样,提案订单项也需要至少 1 个 InventoryTargeting 对象。在这种情况下,网络随机广告 (RON) 提案订单项会通过定位相应广告联盟的根广告单元的方式进行创建。
Java
// Get the NetworkService. NetworkServiceInterface networkService = dfpServices.get(session, NetworkServiceInterface.class); // Get the root ad unit ID used to target the whole site. String rootAdUnitId = networkService.getCurrentNetwork().getEffectiveRootAdUnitId(); // Create inventory targeting. InventoryTargeting inventoryTargeting = new InventoryTargeting(); // Create ad unit targeting for the root ad unit (i.e. the whole network). AdUnitTargeting adUnitTargeting = new AdUnitTargeting(); adUnitTargeting.setAdUnitId(rootAdUnitId); adUnitTargeting.setIncludeDescendants(true); inventoryTargeting.setTargetedAdUnits(new AdUnitTargeting[] {adUnitTargeting}); // Create targeting. Targeting targeting = new Targeting(); targeting.setInventoryTargeting(inventoryTargeting);
Python
... 'targeting': { 'inventoryTargeting': { 'targetedAdUnits': { 'adUnitId': root_ad_unit_id } } }, ...
PHP
// Create ad unit targeting for the root ad unit (i.e. the whole network). $rootAdUnitId = $networkService->getCurrentNetwork() ->getEffectiveRootAdUnitId(); $inventoryTargeting = new InventoryTargeting(); $adUnitTargeting = new AdUnitTargeting(); $adUnitTargeting->setAdUnitId($rootAdUnitId); $adUnitTargeting->setIncludeDescendants(true); $inventoryTargeting->setTargetedAdUnits([$adUnitTargeting]); $targeting = new Targeting(); $targeting->setInventoryTargeting($inventoryTargeting); $proposalLineItem->setTargeting($targeting);
C#
// Get the root ad unit ID used to target the whole site. String rootAdUnitId = networkService.getCurrentNetwork().effectiveRootAdUnitId; // Create inventory targeting. InventoryTargeting inventoryTargeting = new InventoryTargeting(); // Create ad unit targeting for the root ad unit (i.e. the whole network). AdUnitTargeting adUnitTargeting = new AdUnitTargeting(); adUnitTargeting.adUnitId = rootAdUnitId; adUnitTargeting.includeDescendants = true; inventoryTargeting.targetedAdUnits = new AdUnitTargeting[] { adUnitTargeting }; // Create targeting. Targeting targeting = new Targeting(); targeting.inventoryTargeting = inventoryTargeting;
添加所需的 InventoryTargeting
对象后,您就得为预期订单项指定投放开始日期和结束日期,并指定已为 Goal 对象设置的投放信息。
Java
// Set the length of the proposal line item to run. proposalLineItem.setStartDateTime(DateTimes.toDateTime(Instant.now(), "America/New_York")); proposalLineItem.setEndDateTime( DateTimes.toDateTime(Instant.now().plus(Duration.standardDays(30L)), "America/New_York")); // Set pricing for the proposal line item for 1000 impressions at a CPM of $2 // for a total value of $2. Goal goal = new Goal(); goal.setUnits(1000L); goal.setUnitType(UnitType.IMPRESSIONS); proposalLineItem.setGoal(goal); proposalLineItem.setNetCost(new Money("USD", 2000000L)); proposalLineItem.setNetRate(new Money("USD", 2000000L)); proposalLineItem.setRateType(RateType.CPM); // Set delivery specifications for the proposal line item. proposalLineItem.setDeliveryRateType(DeliveryRateType.EVENLY); proposalLineItem.setCreativeRotationType(CreativeRotationType.OPTIMIZED);
Python
... 'startDateTime': start_datetime, 'endDateTime': end_datetime, 'goal': { 'units': '1000', 'unitType': 'IMPRESSIONS', }, 'netCost': { 'currencyCode': 'USD', 'microAmount': '2000000' }, 'netRate': { 'currencyCode': 'USD', 'microAmount': '2000000' }, 'rateType': 'CPM', 'deliveryRateType': 'EVENLY', 'creativeRotationType': 'OPTIMIZED', ...
PHP
// Set the length of the proposal line item to run. $proposalLineItem->setStartDateTime( DfpDateTimes::fromDateTime( new DateTime('now', new DateTimeZone('America/New_York')) ) ); $proposalLineItem->setEndDateTime( DfpDateTimes::fromDateTime( new DateTime('+1 month', new DateTimeZone('America/New_York')) ) ); // Set pricing for the proposal line item for 1000 impressions at a CPM of // $2 for a total value of $2. $goal = new Goal(); $goal->setUnits(1000); $goal->setUnitType(UnitType::IMPRESSIONS); $proposalLineItem->setGoal($goal); $proposalLineItem->setNetCost(new Money('USD', 2000000)); $proposalLineItem->setNetRate(new Money('USD', 2000000)); $proposalLineItem->setRateType(RateType::CPM); // Set delivery specifications for the proposal line item. $proposalLineItem->setDeliveryRateType(DeliveryRateType::EVENLY); $proposalLineItem->setCreativeRotationType(CreativeRotationType::OPTIMIZED);
C#
// Set the length of the proposal line item to run. proposalLineItem.startDateTime = DateTimeUtilities.FromDateTime(System.DateTime.Now.AddDays(7), "America/New_York"); proposalLineItem.endDateTime = DateTimeUtilities.FromDateTime(System.DateTime.Now.AddDays(30), "America/New_York"); // Set pricing for the proposal line item for 1000 impressions at a CPM of $2 // for a total value of $2. proposalLineItem.goal = new Goal() { unitType = UnitType.IMPRESSIONS, units = 1000L }; proposalLineItem.netCost = new Money() { currencyCode = "USD", microAmount = 2000000L }; proposalLineItem.netRate = new Money() { currencyCode = "USD", microAmount = 2000000L }; proposalLineItem.rateType = RateType.CPM; // Set delivery specifications for the proposal line item. proposalLineItem.deliveryRateType = DeliveryRateType.EVENLY; proposalLineItem.creativeRotationType = CreativeRotationType.OPTIMIZED;
您还可以替换提案订单项中从相应提案正常沿用的结算信息。您可以设置 Proposal 对象允许的相同 BillingCap、BillingSource 和 BillingSchedule 字段。
Java
// Set billing specifications for the proposal line item. proposalLineItem.setBillingCap(BillingCap.CAPPED_CUMULATIVE); proposalLineItem.setBillingSource(BillingSource.THIRD_PARTY_VOLUME);
Python
... 'billingCap': 'CAPPED_CUMULATIVE', 'billingSource': 'THIRD_PARTY_VOLUME', ...
PHP
// Set billing specifications for the proposal line item. $proposalLineItem->setBillingCap(BillingCap::CAPPED_CUMULATIVE); $proposalLineItem->setBillingSource(BillingSource::THIRD_PARTY_VOLUME);
C#
// Set billing specifications for the proposal line item. proposalLineItem.billingCap = BillingCap.CAPPED_CUMULATIVE; proposalLineItem.billingSource = BillingSource.THIRD_PARTY_VOLUME;
设置完这些字段后,您便可通过对 ProposalLineItem
对象的数组调用 createProposalLineItems 来新建提案订单项。
Java
// Create the proposal line item on the server. ProposalLineItem[] proposalLineItems = proposalLineItemService.createProposalLineItems( new ProposalLineItem[] {proposalLineItem});
Python
# Add proposal line items. proposal_line_items = proposal_line_item_service.createProposalLineItems( [proposal_line_item])
PHP
// Create the proposal line items on the server. $results = $proposalLineItemService->createProposalLineItems([$proposalLineItem]);
C#
// Create the proposal line item on the server. ProposalLineItem[] proposalLineItems = proposalLineItemService.createProposalLineItems( new ProposalLineItem[] { proposalLineItem });
后续步骤
- 提交提案以供审批
- 审批 WorkflowConditionRequests