Reminder: v201708 will be sunset on August 31, 2018.

DFP 销售管理系统产品模板和产品

本指南阐述了产品的定义,并逐步介绍了如何通过 API 中的 ProductTemplate 对象创建 Product 对象。

基础入门

DFP 销售管理系统中的产品由销售团队创建,用于代表要销售的广告资源细分。从实体的角度来看,它们是订单项的提案,即用于创建 ProposalLineItem 对象的模板。在创建产品模板后,系统便会在后台自动生成产品。这些对象定义了提案订单项字段的默认值,如名称、产品类型、费率类型以及定位预设(用于指定可以默认设置的定位以及可自定义的定位字段)。创建提案订单项需组合使用 RateCardProduct 对象(已启用)。

创建产品

要创建产品,请先在本地创建 ProductTemplate 对象,为其指定名称并视需要添加说明,使其与目录中的其他产品模板区别开来:

Java

  // Create a product template.
  ProductTemplate productTemplate = new ProductTemplate();
  productTemplate.setName("Product template #" + new Random().nextInt(Integer.MAX_VALUE));
  productTemplate.setDescription("This product template creates standard proposal line items "
      + "targeting Chrome browsers with product segmentation on ad units and geo targeting.");
    

Python

  # Initialize appropriate service.
  product_template_service = client.GetService(
      'ProductTemplateService', version='v201708')

  # Create a product template.
  product_template = {
      'name': ('Product template #%d' % uuid.uuid4()),
      'description': ('This product template creates standard proposal line '
                      'items targeting Chrome browsers with product '
                      'segmentation on ad units and geo targeting.'),
      ...
    

PHP

        $productTemplateService = $dfpServices->get($session, ProductTemplateService::class);

        $productTemplate = new ProductTemplate();
        $productTemplate->setName('Product template #' . uniqid());
        $productTemplate->setDescription(
            'This product template creates standard '
            . 'proposal line items targeting Chrome browsers with product '
            . 'segmentation on ad units and geo targeting.'
        );
    

C#

  using (ProductTemplateService productTemplateService =
      (ProductTemplateService) user.GetService(DfpService.v201708.ProductTemplateService))

    // Create a product template.
    ProductTemplate productTemplate = new ProductTemplate();
    productTemplate.name = "Product template #" + new Random().Next(int.MaxValue);
    productTemplate.description = "This product template creates standard proposal line items "
        + "targeting Chrome browsers with product segmentation on ad units and geo targeting.";
    

您可以在其中设置名称宏。此字段会生成已创建产品的名称,并会使用指定的产品细分通过一个产品模板创建多个产品。

Java

  // Set the name macro which will be used to generate the names of the products.
  // This will create a segmentation based on the line item type, ad unit, and location.
  productTemplate.setNameMacro("<line-item-type> - <ad-unit> - <template-name> - <location>");
    

Python

      ...
      'nameMacro': ('<line-item-type> - <ad-unit> - '
                    '<template-name> - <location>'),
      ...
    

PHP

        // Set the name macro which will be used to generate the names of the
        // products. This will create a segmentation based on the line item type, ad
        // unit, and location.
        $productTemplate->setNameMacro(
            '<line-item-type> - <ad-unit> - <template-name> - <location>'
        );
    

C#

    // Set the name macro which will be used to generate the names of the products.
    // This will create a segmentation based on the line item type, ad unit, and location.
    productTemplate.nameMacro = "<line-item-type> - <ad-unit> - <template-name> - <location>";
    

以下字段与提案订单项的广告投放管理规范(如订单项类型、产品类型、费率)以及广告素材/广告素材投放设置相关:

Java

  // Set the product type so the created proposal line items will be trafficked in DFP.
  productTemplate.setProductType(ProductType.DFP);

  // Set rate type to create CPM priced proposal line items.
  productTemplate.setRateType(RateType.CPM);
  productTemplate.setDeliveryRateType(DeliveryRateType.AS_FAST_AS_POSSIBLE);

  // Optionally set the creative rotation of the product to serve one or more creatives.
  productTemplate.setRoadblockingType(RoadblockingType.ONE_OR_MORE);

  // Create the master creative placeholder.
  CreativePlaceholder creativeMasterPlaceholder = new CreativePlaceholder();
  creativeMasterPlaceholder.setSize(new Size(728, 90, false));

  // Create companion creative placeholders.
  CreativePlaceholder companionCreativePlaceholder = new CreativePlaceholder();
  companionCreativePlaceholder.setSize(new Size(300, 250, false));

  // Set the size of creatives that can be associated with the product template.
  productTemplate.setCreativePlaceholders(
      new CreativePlaceholder[] {creativeMasterPlaceholder, companionCreativePlaceholder});

  // Set the type of proposal line item to be created from the product template.
  productTemplate.setLineItemType(LineItemType.STANDARD);
    

Python

      ...
      'productType': 'DFP',
      'rateType': 'CPM',
      'roadblockingType': 'ONE_OR_MORE',
      'deliveryRateType': 'AS_FAST_AS_POSSIBLE',
      'creativePlaceholders': [
          {
              'size': {
                  'width': '728',
                  'height': '90'
              }
          },
          {
              'size': {
                  'width': '300',
                  'height': '250'
              }
          }
      ],
      'lineItemType': 'STANDARD',
      ...
    

PHP

        // Set the product type so the created proposal line items will be
        // trafficked in DFP.
        $productTemplate->setProductType(ProductType::DFP);

        // Set rate type to create CPM priced proposal line items.
        $productTemplate->setRateType(RateType::CPM);
        $productTemplate->setDeliveryRateType(
            DeliveryRateType::AS_FAST_AS_POSSIBLE
        );

        // Optionally set the creative rotation of the product to serve one or more
        // creatives.
        $productTemplate->setRoadblockingType(RoadblockingType::ONE_OR_MORE);

        // Set the size of creatives that can be associated with the product
        // template.
        $creativePlaceholder1 = new CreativePlaceholder();
        $size = new Size();
        $size->setWidth(728);
        $size->setHeight(90);
        $size->setIsAspectRatio(false);
        $creativePlaceholder1->setSize($size);
        $creativePlaceholder2 = new CreativePlaceholder();
        $size = new Size();
        $size->setWidth(300);
        $size->setHeight(250);
        $size->setIsAspectRatio(false);
        $creativePlaceholder2->setSize($size);
        $productTemplate->setCreativePlaceholders(
            [$creativePlaceholder1, $creativePlaceholder2]
        );

        // Set the type of proposal line item to be created from the product
        // template.
        $productTemplate->setLineItemType(LineItemType::STANDARD);
    

C#

    // Set the product type so the created proposal line items will be trafficked in DFP.
    productTemplate.productType = ProductType.DFP;

    // Set rate type to create CPM priced proposal line items.
    productTemplate.rateType = RateType.CPM;

    // Optionally set the creative rotation of the product to serve one or more creatives.
    productTemplate.roadblockingType = RoadblockingType.ONE_OR_MORE;
    productTemplate.deliveryRateType = DeliveryRateType.AS_FAST_AS_POSSIBLE;

    // Create the master creative placeholder.
    CreativePlaceholder creativeMasterPlaceholder = new CreativePlaceholder();
    creativeMasterPlaceholder.size =
        new Size() { width = 728, height = 90, isAspectRatio = false };

    // Create companion creative placeholders.
    CreativePlaceholder companionCreativePlaceholder = new CreativePlaceholder();
    companionCreativePlaceholder.size =
        new Size() { width = 300, height = 250, isAspectRatio = false };

    // Set the size of creatives that can be associated with the product template.
    productTemplate.creativePlaceholders =
        new CreativePlaceholder[] { creativeMasterPlaceholder, companionCreativePlaceholder };

    // Set the type of proposal line item to be created from the product template.
    productTemplate.lineItemType = LineItemType.STANDARD;
    

然后,您可以为产品指定定位默认值,通过您产品创建的提案订单项将会沿用这些值。与提案订单项类似的是,您可以直接在此产品模板上添加定位。可通过 ProductTemplateTargeting 对象完成此操作。

Java

  // Get the root ad unit ID used to target the whole site.
  String rootAdUnitId = networkService.getCurrentNetwork().getEffectiveRootAdUnitId();

  // Create ad unit targeting for the root ad unit (i.e. the whole network).
  AdUnitTargeting adUnitTargeting = new AdUnitTargeting();
  adUnitTargeting.setAdUnitId(rootAdUnitId);
  adUnitTargeting.setIncludeDescendants(true);

  // Create geo targeting for the US.
  Location countryLocation = new Location();
  countryLocation.setId(2840L);

  // Create geo targeting for Hong Kong.
  Location regionLocation = new Location();
  regionLocation.setId(2344L);

  GeoTargeting geoTargeting = new GeoTargeting();
  geoTargeting.setTargetedLocations(new Location[] {countryLocation, regionLocation});

  // Add browser targeting to Chrome on the product template distinct from product segmentation.
  Browser chromeBrowser = new Browser();
  chromeBrowser.setId(500072L);

  BrowserTargeting browserTargeting = new BrowserTargeting();
  browserTargeting.setBrowsers(new Browser[] {chromeBrowser});

  TechnologyTargeting technologyTargeting = new TechnologyTargeting();
  technologyTargeting.setBrowserTargeting(browserTargeting);

  Targeting productTemplateTargeting = new Targeting();
  productTemplateTargeting.setTechnologyTargeting(technologyTargeting);

  productTemplate.setBuiltInTargeting(productTemplateTargeting);
    

Python

      ...
      'customizableAttributes': {
          'allowPlacementTargetingCustomization': True,
      },
      'builtInTargeting': {
          'technologyTargeting': {
              # Set browser targeting to Chrome.
              'browserTargeting': {
                  {
                      'browsers': [
                          {
                              'id': '500072'
                          }
                      ]
                  }
              }
          }
      },
      ...
    

PHP

        // Add browser targeting to Chrome on the product template distinct from
        // product segmentation.
        $targeting = new Targeting();
        $technologyTargeting = new TechnologyTargeting();
        $browserTargeting = new BrowserTargeting();
        $browser = new Browser();
        $browser->setId(500072);
        $browserTargeting->setBrowsers([$browser]);
        $technologyTargeting->setBrowserTargeting($browserTargeting);
        $targeting->setTechnologyTargeting($technologyTargeting);
        $productTemplate->setBuiltInTargeting($targeting);

        // Allow placement targeting to be customized on the proposal line item.
        $customizableAttributes = new CustomizableAttributes();
        $customizableAttributes->setAllowPlacementTargetingCustomization(true);
        $productTemplate->setCustomizableAttributes($customizableAttributes);

        // Add inventory and geo targeting as product segmentation.
        $productSegmentation = new ProductSegmentation();
        // Create ad unit targeting for the root ad unit (i.e. the whole network).
        $adUnitTargeting = new AdUnitTargeting();
        $adUnitTargeting->setAdUnitId(
            $networkService->getCurrentNetwork()
                ->getEffectiveRootAdUnitId()
        );
        $adUnitTargeting->setIncludeDescendants(true);
        $productSegmentation->setAdUnitSegments([$adUnitTargeting]);
        // Create geo targeting for the US and Hong Kong.
        $geoTargeting = new GeoTargeting();
        $location1 = new Location();
        $location1->setId(2840); // US
        $location2 = new Location();
        $location2->setId(2344); // Hong Kong
        $geoTargeting->setTargetedLocations([$location1, $location2]);
    

C#

    // Get the root ad unit ID used to target the whole site.
    String rootAdUnitId = networkService.getCurrentNetwork().effectiveRootAdUnitId;

    // Create ad unit targeting for the root ad unit (i.e. the whole network).
    AdUnitTargeting adUnitTargeting = new AdUnitTargeting();
    adUnitTargeting.adUnitId = rootAdUnitId;
    adUnitTargeting.includeDescendants = true;

    // Create geo targeting for the US.
    Location countryLocation = new Location();
    countryLocation.id = 2840L;

    // Create geo targeting for Hong Kong.
    Location regionLocation = new Location();
    regionLocation.id = 2344L;

    GeoTargeting geoTargeting = new GeoTargeting();
    geoTargeting.targetedLocations = new Location[] { countryLocation, regionLocation };

    // Add browser targeting to Chrome on the product template distinct from product
    // segmentation.
    Browser chromeBrowser = new Browser();
    chromeBrowser.id = 500072L;

    BrowserTargeting browserTargeting = new BrowserTargeting();
    browserTargeting.browsers = new Browser[] { chromeBrowser };

    TechnologyTargeting technologyTargeting = new TechnologyTargeting();
    technologyTargeting.browserTargeting = browserTargeting;

    Targeting productTemplateTargeting = new Targeting();
    productTemplateTargeting.technologyTargeting = technologyTargeting;

    productTemplate.builtInTargeting = productTemplateTargeting;

    productTemplate.customizableAttributes = new CustomizableAttributes() {
      allowPlacementTargetingCustomization = true
    };
    

通过产品细分,您可以创建共用一组提案订单项设置的多个产品,只需组合多个定位选项即可。在上面的部分中,您为 GeoTargeting 对象添加了多个地理位置。在您将该细分添加为此产品模板上的细分后,它会创建两个产品,一个定位到美国,另一个定位到香港。

Java

  // Add inventory and geo targeting as product segmentation.
  ProductSegmentation productSegmentation = new ProductSegmentation();
  productSegmentation.setAdUnitSegments(new AdUnitTargeting[] {adUnitTargeting});
  productSegmentation.setGeoSegment(geoTargeting);

  productTemplate.setProductSegmentation(productSegmentation);
    

Python

      ...
      'productSegmentation': {
          'geoSegment': {
              'targetedLocations': [
                  {'id': '2840',
                   'displayName': 'US'},
                  {'id': '2344',
                   'displayName': 'Hong Kong'}
              ]
          },
          'adUnitSegments': [{
              'adUnitId': (network_service.getCurrentNetwork()[
                  'effectiveRootAdUnitId']),
              'includeDescendants': 'true'
          }]
      }
      ...
    

PHP

        $productSegmentation->setGeoSegment($geoTargeting);
        $productTemplate->setProductSegmentation($productSegmentation);
    

C#

    // Add inventory and geo targeting as product segmentation.
    ProductSegmentation productSegmentation = new ProductSegmentation();
    productSegmentation.adUnitSegments = new AdUnitTargeting[] { adUnitTargeting };
    productSegmentation.geoSegment = geoTargeting;

    productTemplate.productSegmentation = productSegmentation;
    

待设定这些字段后,您便可通过对一组产品模板调用 createProductTemplates 来新建 ProductTemplate 对象:

Java

  // Create the product template on the server.
  ProductTemplate[] productTemplates =
      productTemplateService.createProductTemplates(new ProductTemplate[] {productTemplate});
    

Python

  # Create product templates on the server.
  product_templates = product_template_service.createProductTemplates(
      [product_template])
    

PHP

        // Create the product template on the server.
        $results = $productTemplateService->createProductTemplates([$productTemplate]);
    

C#

    // Create the product template on the server.
    ProductTemplate[] productTemplates = productTemplateService.createProductTemplates(
        new ProductTemplate[] { productTemplate });
    

创建的产品模板以及相应产品均将处于 INACTIVE 状态。

启用产品模板

您必须先启用产品模板,然后才能使用通过此产品模板创建的产品。为此,请使用 ActivateProductTemplates 操作:

Java

    // Create a statement to select a product template.
    StatementBuilder statementBuilder = new StatementBuilder()
        .where("WHERE id = :id")
        .orderBy("id ASC")
        .limit(StatementBuilder.SUGGESTED_PAGE_LIMIT)
        .withBindVariableValue("id", productTemplateId);

      // Create action.
      com.google.api.ads.dfp.axis.v201708.ActivateProductTemplates action =
          new com.google.api.ads.dfp.axis.v201708.ActivateProductTemplates();

      // Perform action.
      UpdateResult result =
          productTemplateService.performProductTemplateAction(
              action, statementBuilder.toStatement());
    

Python

  # Create query.
  statement = (dfp.StatementBuilder()
               .Where('id = :id')
               .WithBindVariable('id', long(product_template_id))
               .Limit(1))

      # Perform action.
      result = product_template_service.performProductTemplateAction(
          {'xsi_type': 'ActivateProductTemplates'}, statement.ToStatement())
    

PHP

        // Create a statement to select the product templates to activate.
        $pageSize = StatementBuilder::SUGGESTED_PAGE_LIMIT;
        $statementBuilder = (new StatementBuilder())->where('id = :id')
            ->orderBy('id ASC')
            ->limit($pageSize)
            ->withBindVariableValue('id', $productTemplateId);

            // Create and perform action.
            $action = new ActivateProductTemplatesAction();
            $result = $productTemplateService->performProductTemplateAction(
                $action,
                $statementBuilder->toStatement()
            );
    

C#

    // Create statement to select a product template by ID.
    StatementBuilder statementBuilder = new StatementBuilder()
        .Where("id = :id")
        .OrderBy("id ASC")
        .Limit(StatementBuilder.SUGGESTED_PAGE_LIMIT)
        .AddValue("id", productTemplateId);

    // Create action.
    Google.Api.Ads.Dfp.v201708.ActivateProductTemplates action =
        new Google.Api.Ads.Dfp.v201708.ActivateProductTemplates();

    // Perform action.
    UpdateResult result = productTemplateService.performProductTemplateAction(action,
        statementBuilder.ToStatement());
    

这会启用此产品模板以及相应产品。它们现在便可用于创建提案订单项。

提取产品

新建 ProductTemplate 对象后,您可以通过查询此产品模板返回的 ID 来获取已创建的产品。

Java

  // Create a statement to select products.
  StatementBuilder statementBuilder = new StatementBuilder()
      .where("productTemplateId = :productTemplateId")
      .orderBy("id ASC")
      .limit(StatementBuilder.SUGGESTED_PAGE_LIMIT)
      .withBindVariableValue("productTemplateId", productTemplateId);

    ProductPage page =
        productService.getProductsByStatement(statementBuilder.toStatement());
    

Python

  # Create a statement to select products.
  statement = (dfp.StatementBuilder()
               .Where('productTemplateId = :productTemplateId')
               .WithBindVariable('productTemplateId', product_template_id))

    response = product_service.getProductsByStatement(statement.ToStatement())
    

PHP

        // Create a statement to select products.
        $pageSize = StatementBuilder::SUGGESTED_PAGE_LIMIT;
        $statementBuilder =
            (new StatementBuilder())->where('productTemplateId = :productTemplateId')
                ->orderBy(
                    'id ASC'
                )
                ->limit($pageSize)
                ->withBindVariableValue('productTemplateId', $productTemplateId);

            $page = $productService->getProductsByStatement(
                $statementBuilder->toStatement()
            );
    

C#

    // Create a statement to select products.
    int pageSize = StatementBuilder.SUGGESTED_PAGE_LIMIT;
    StatementBuilder statementBuilder = new StatementBuilder()
        .Where("productTemplateId = :productTemplateId")
        .OrderBy("id ASC")
        .Limit(pageSize)
        .AddValue("productTemplateId", productTemplateId);

  ProductPage page = productService.getProductsByStatement(
      statementBuilder.ToStatement());
    

本地同步产品

如果您要尝试制作一份所有产品的本地目录,则可以通过在首次查询中选择所有产品来实现,所使用的语句如下所示:

Java

  StatementBuilder statementBuilder = new StatementBuilder()
      .orderBy("id ASC")
      .limit(StatementBuilder.SUGGESTED_PAGE_LIMIT);
    

Python

  statement = dfp.FilterStatement('ORDER BY id ASC')
    

PHP

  $statementBuilder->OrderBy('id ASC')
      ->Limit(StatementBuilder::SUGGESTED_PAGE_LIMIT);
    

C#

  StatementBuilder statementBuilder = new StatementBuilder()
      .OrderBy("id ASC")
      .Limit(StatementBuilder.SUGGESTED_PAGE_LIMIT);
    

在后续提取过程中,使用 Product 对象的 lastModifiedDateTime 属性进行过滤。通过将上一次同步日期传递到 lastModifiedDateTime 变量中,您可以只提取已更改的产品,这样做能够显著提高提取速度。

Java

  StatementBuilder statementBuilder = new StatementBuilder()
      .where("lastModifiedDateTime > :lastModifiedDateTime")
      .orderBy("id ASC")
      .limit(StatementBuilder.SUGGESTED_PAGE_LIMIT)
      .withBindVariable("lastModifiedDateTime", lastSyncDateTime);
    

Python

  values = [{
      'key': 'dateTimeString',
      'value': {
          'xsi_type': 'TextValue',
          'value': lastSyncDateTime.strftime('%Y-%m-%dT%H:%M:%S')
      }
  }, {
      'key': 'orderId',
      'value': {
          'xsi_type': 'NumberValue',
          'value': order_id
      }
  }]
  query = 'WHERE lastModifiedDateTime >= :dateTimeString AND orderId = :orderId'
  statement = dfp.FilterStatement(query, values)
    

PHP

  $statementBuilder->Where('lastModifiedDateTime >= :lastModifiedDateTime')
      ->OrderBy('id ASC')
      ->Limit(StatementBuilder::SUGGESTED_PAGE_LIMIT)
      ->WithBindVariableValue(
          'lastModifiedDateTime',
          DateTimeUtils::ToDfpDateTime(lastSyncDateTime)
      );
    

C#

   StatementBuilder statementBuilder = new StatementBuilder()
       .Where("lastModifiedDateTime > :lastModifiedDateTime")
       .OrderBy("id ASC")
       .Limit(StatementBuilder.SUGGESTED_PAGE_LIMIT)
       .AddValue("lastModifiedDateTime", lastSyncDateTime);
    

通过将您广告联盟中的所有产品都添加到本地版本的“目录”中,您不必另外调用 API,即可重复使用这些产品。

后续步骤

发送以下问题的反馈:

此网页
DoubleClick for Publishers API
DoubleClick for Publishers API
需要帮助?请访问我们的支持页面