Campaign Manager 360 API v3.5 已被弃用,并将于 2023 年 2 月 20 日停用。所有用户都必须在该截止日期之前迁移到新版 API。

常见的广告投放管理任务

本页中简要介绍了如何使用 DCM/DFA Reporting and Trafficking API 执行一些最常见的广告投放管理任务。

常规编码提示

  • 必需的及可选的属性和参数 - 如需了解某个属性或参数是否为进行 API 调用所必需的属性或参数,请参阅参考文档
  • 使用通配符按名称搜索 - 按名称搜索对象时,您可以使用星号 (*) 通配符。一个星号可以表示零个或多个任意字符。该 API 还支持隐式子字符串搜索,因此搜索“abc”将隐含搜索“*abc*”。
  • 更新与修补 - 您可以采用以下两种方式修改现有对象:
    1. 更新 - 更新对象时,所有字段在插入时都会被覆盖。因此,请务必先加载要更新的对象,然后再对该对象进行任何更改。否则,未出现在更新请求中的所有字段都将被取消设置。
    2. 修补 - 修补对象时,只有指定的字段在插入时会被覆盖。若采用这种方式,您可以创建一个新对象,为其分配要更新的对象所用的同一 ID,设置要更新的字段,然后执行修补请求。
  • 尺寸 - 实际尺寸由尺寸服务定义的 Size 对象表示。帐号中会提供一系列标准尺寸,并且您可以向该列表中添加自定义尺寸。
  • 日期和时间 - 您可以使用当地时区以 RFC 3339 格式保存日期/时间;该 API 返回的所有值均采用世界协调时间 (UTC)。这与网站不同,后者的日期和时间都是以您配置的时区显示(默认为美国/纽约时间)。

创建广告客户

C#

  1. 创建一个 Advertiser 对象,并设置其必需的 namestatus 属性。
    // Create the advertiser structure.
    Advertiser advertiser = new Advertiser();
    advertiser.Name = advertiserName;
    advertiser.Status = "APPROVED";
    
  2. 通过调用 advertisers.insert() 来保存该广告客户。
    // Create the advertiser.
    Advertiser result = service.Advertisers.Insert(advertiser, profileId).Execute();
    

Java

  1. 创建一个 Advertiser 对象,并设置其必需的 namestatus 属性。
    // Create the advertiser structure.
    Advertiser advertiser = new Advertiser();
    advertiser.setName(advertiserName);
    advertiser.setStatus("APPROVED");
    
  2. 通过调用 advertisers.insert() 来保存该广告客户。
    // Create the advertiser.
    Advertiser result = reporting.advertisers().insert(profileId, advertiser).execute();
    

PHP

  1. 创建一个 Advertiser 对象,并设置其必需的 namestatus 属性。
    $advertiser = new Google_Service_Dfareporting_Advertiser();
    $advertiser->setName($values['advertiser_name']);
    $advertiser->setStatus('APPROVED');
    
  2. 通过调用 advertisers.insert() 来保存该广告客户。
    $result = $this->service->advertisers->insert(
        $values['user_profile_id'],
        $advertiser
    );
    

Python

  1. 创建一个 Advertiser 对象,并设置其必需的 namestatus 属性。
    # Construct and save advertiser.
    advertiser = {
        'name': 'Test Advertiser',
        'status': 'APPROVED'
    }
    
  2. 通过调用 advertisers.insert() 来保存该广告客户。
    request = service.advertisers().insert(
        profileId=profile_id, body=advertiser)
    
    # Execute request and print response.
    response = request.execute()
    

Ruby

  1. 创建一个 Advertiser 对象,并设置其必需的 namestatus 属性。
    # Create a new advertiser resource to insert.
    advertiser = DfareportingUtils::API_NAMESPACE::Advertiser.new(
      name: format('Example Advertiser #%s', SecureRandom.hex(3)),
      status: 'APPROVED'
    )
    
  2. 通过调用 advertisers.insert() 来保存该广告客户。
    # Insert the advertiser.
    result = service.insert_advertiser(profile_id, advertiser)
    

创建广告系列

C#

  1. 创建一个 Campaign 对象,并设置其必需的属性:

    • advertiserId - 要与该广告系列关联的广告客户。
    • name - 此名称在该广告客户的所有广告系列中必须是独一无二的。
    • defaultLandingPageId - 当用户点击该广告系列中未被分配着陆页的广告时,系统便会自动将他们转到这个着陆页。您可以调用 advertiserLandingPages.list 来查找现有的着陆页,也可以调用 advertiserLandingPages.insert 来创建新着陆页。
    • 开始结束日期 - 必须是未来日期,可以精确到日。如需了解详情,请参阅常规编码信息中的“日期和时间”项。在截止到指定的广告系列结束日期时,如果仍未达到合同中指定的操作次数,那么个别广告日期可以超出结束日期,以便发布商尽力履行合同。
    // Locate an advertiser landing page to use as a default.
    LandingPage defaultLandingPage = getAdvertiserLandingPage(service, profileId, advertiserId);
    
    // Create the campaign structure.
    Campaign campaign = new Campaign();
    campaign.Name = campaignName;
    campaign.AdvertiserId = advertiserId;
    campaign.Archived = false;
    campaign.DefaultLandingPageId = defaultLandingPage.Id;
    
    // Set the campaign start date. This example uses today's date.
    campaign.StartDate =
        DfaReportingDateConverterUtil.convertToDateString(DateTime.Now);
    
    // Set the campaign end date. This example uses one month from today's date.
    campaign.EndDate =
        DfaReportingDateConverterUtil.convertToDateString(DateTime.Now.AddMonths(1));
    
  2. 通过调用 campaigns.insert() 来保存该广告系列。

    // Insert the campaign.
    Campaign result = service.Campaigns.Insert(campaign, profileId).Execute();
    

Java

  1. 创建一个 Campaign 对象,并设置其必需的属性:

    • advertiserId - 要与该广告系列关联的广告客户。
    • name - 此名称在该广告客户的所有广告系列中必须是独一无二的。
    • defaultLandingPageId - 当用户点击该广告系列中未被分配着陆页的广告时,系统便会自动将他们转到这个着陆页。您可以调用 advertiserLandingPages.list 来查找现有的着陆页,也可以调用 advertiserLandingPages.insert 来创建新着陆页。
    • 开始结束日期 - 必须是未来日期,可以精确到日。如需了解详情,请参阅常规编码信息中的“日期和时间”项。在截止到指定的广告系列结束日期时,如果仍未达到合同中指定的操作次数,那么个别广告日期可以超出结束日期,以便发布商尽力履行合同。
    // Locate an advertiser landing page to use as a default.
    LandingPage defaultLandingPage = getAdvertiserLandingPage(reporting, profileId, advertiserId);
    
    // Create the campaign structure.
    Campaign campaign = new Campaign();
    campaign.setName(campaignName);
    campaign.setAdvertiserId(advertiserId);
    campaign.setArchived(false);
    campaign.setDefaultLandingPageId(defaultLandingPage.getId());
    
    // Set the campaign start date. This example uses today's date.
    Calendar today = Calendar.getInstance();
    DateTime startDate = new DateTime(true, today.getTimeInMillis(), null);
    campaign.setStartDate(startDate);
    
    // Set the campaign end date. This example uses one month from today's date.
    Calendar nextMonth = Calendar.getInstance();
    nextMonth.add(Calendar.MONTH, 1);
    DateTime endDate = new DateTime(true, nextMonth.getTimeInMillis(), null);
    campaign.setEndDate(endDate);
    
  2. 通过调用 campaigns.insert() 来保存该广告系列。

    // Insert the campaign.
    Campaign result = reporting.campaigns().insert(profileId, campaign).execute();
    

PHP

  1. 创建一个 Campaign 对象,并设置其必需的属性:

    • advertiserId - 要与该广告系列关联的广告客户。
    • name - 此名称在该广告客户的所有广告系列中必须是独一无二的。
    • defaultLandingPageId - 当用户点击该广告系列中未被分配着陆页的广告时,系统便会自动将他们转到这个着陆页。您可以调用 advertiserLandingPages.list 来查找现有的着陆页,也可以调用 advertiserLandingPages.insert 来创建新着陆页。
    • 开始结束日期 - 必须是未来日期,可以精确到日。如需了解详情,请参阅常规编码信息中的“日期和时间”项。在截止到指定的广告系列结束日期时,如果仍未达到合同中指定的操作次数,那么个别广告日期可以超出结束日期,以便发布商尽力履行合同。
    $startDate = new DateTime('today');
    $endDate = new DateTime('+1 month');
    
    $campaign = new Google_Service_Dfareporting_Campaign();
    $campaign->setAdvertiserId($values['advertiser_id']);
    $campaign->setDefaultLandingPageId($values['default_landing_page_id']);
    $campaign->setName($values['campaign_name']);
    $campaign->setStartDate($startDate->format('Y-m-d'));
    $campaign->setEndDate($endDate->format('Y-m-d'));
    
  2. 通过调用 campaigns.insert() 来保存该广告系列。

    $result = $this->service->campaigns->insert(
        $values['user_profile_id'],
        $campaign
    );
    

Python

  1. 创建一个 Campaign 对象,并设置其必需的属性:

    • advertiserId - 要与该广告系列关联的广告客户。
    • name - 此名称在该广告客户的所有广告系列中必须是独一无二的。
    • defaultLandingPageId - 当用户点击该广告系列中未被分配着陆页的广告时,系统便会自动将他们转到这个着陆页。您可以调用 advertiserLandingPages.list 来查找现有的着陆页,也可以调用 advertiserLandingPages.insert 来创建新着陆页。
    • 开始结束日期 - 必须是未来日期,可以精确到日。如需了解详情,请参阅常规编码信息中的“日期和时间”项。在截止到指定的广告系列结束日期时,如果仍未达到合同中指定的操作次数,那么个别广告日期可以超出结束日期,以便发布商尽力履行合同。
    # Locate an advertiser landing page to use as a default.
    default_landing_page = get_advertiser_landing_page(service, profile_id,
                                                       advertiser_id)
    
    # Construct and save campaign.
    campaign = {
        'name': 'Test Campaign #%s' % uuid.uuid4(),
        'advertiserId': advertiser_id,
        'archived': 'false',
        'defaultLandingPageId': default_landing_page['id'],
        'startDate': '2015-01-01',
        'endDate': '2020-01-01'
    }
    
  2. 通过调用 campaigns.insert() 来保存该广告系列。

    request = service.campaigns().insert(profileId=profile_id, body=campaign)
    
    # Execute request and print response.
    response = request.execute()
    

Ruby

  1. 创建一个 Campaign 对象,并设置其必需的属性:

    • advertiserId - 要与该广告系列关联的广告客户。
    • name - 此名称在该广告客户的所有广告系列中必须是独一无二的。
    • defaultLandingPageId - 当用户点击该广告系列中未被分配着陆页的广告时,系统便会自动将他们转到这个着陆页。您可以调用 advertiserLandingPages.list 来查找现有的着陆页,也可以调用 advertiserLandingPages.insert 来创建新着陆页。
    • 开始结束日期 - 必须是未来日期,可以精确到日。如需了解详情,请参阅常规编码信息中的“日期和时间”项。在截止到指定的广告系列结束日期时,如果仍未达到合同中指定的操作次数,那么个别广告日期可以超出结束日期,以便发布商尽力履行合同。
    # Locate an advertiser landing page to use as a default.
    default_landing_page = get_advertiser_landing_page(service, profile_id,
      advertiser_id)
    
    # Create a new campaign resource to insert.
    campaign = DfareportingUtils::API_NAMESPACE::Campaign.new(
      advertiser_id: advertiser_id,
      archived: false,
      default_landing_page_id: default_landing_page.id,
      name: format('Example Campaign #%s', SecureRandom.hex(3)),
      start_date: '2014-01-01',
      end_date: '2020-01-01'
    )
    
  2. 通过调用 campaigns.insert() 来保存该广告系列。

    # Insert the campaign.
    result = service.insert_campaign(profile_id, campaign)
    

创建展示位置

C#

  1. 创建一个 Placement 对象,并设置必需的展示位置属性(包括 campaignIdsiteId)。此外,请务必根据您与网站之间的协商结果准确设置该展示位置的类型和尺寸。
    // Create the placement.
    Placement placement = new Placement();
    placement.Name = placementName;
    placement.CampaignId = campaignId;
    placement.Compatibility = "DISPLAY";
    placement.PaymentSource = "PLACEMENT_AGENCY_PAID";
    placement.SiteId = dfaSiteId;
    placement.TagFormats = new List<string>() { "PLACEMENT_TAG_STANDARD" };
    
    // Set the size of the placement.
    Size size = new Size();
    size.Id = sizeId;
    placement.Size = size;
    
  2. 创建一个新的 PricingSchedule 对象,以分配给该展示位置。
    // Set the pricing schedule for the placement.
    PricingSchedule pricingSchedule = new PricingSchedule();
    pricingSchedule.EndDate = campaign.EndDate;
    pricingSchedule.PricingType = "PRICING_TYPE_CPM";
    pricingSchedule.StartDate = campaign.StartDate;
    placement.PricingSchedule = pricingSchedule;
    
  3. 通过调用 placements.insert() 来保存该 Placement 对象。如果您要使用系统所返回的 ID 将该对象分配给 Ad 或 Creative,请务必妥善存储这个 ID。
    // Insert the placement.
    Placement result = service.Placements.Insert(placement, profileId).Execute();
    

Java

  1. 创建一个 Placement 对象,并设置必需的展示位置属性(包括 campaignIdsiteId)。此外,请务必根据您与网站之间的协商结果准确设置该展示位置的类型和尺寸。
    // Create the placement.
    Placement placement = new Placement();
    placement.setName(placementName);
    placement.setCampaignId(campaignId);
    placement.setCompatibility("DISPLAY");
    placement.setPaymentSource("PLACEMENT_AGENCY_PAID");
    placement.setSiteId(dfaSiteId);
    placement.setTagFormats(ImmutableList.of("PLACEMENT_TAG_STANDARD"));
    
    // Set the size of the placement.
    Size size = new Size();
    size.setId(sizeId);
    placement.setSize(size);
    
  2. 创建一个新的 PricingSchedule 对象,以分配给该展示位置。
    // Set the pricing schedule for the placement.
    PricingSchedule pricingSchedule = new PricingSchedule();
    pricingSchedule.setEndDate(campaign.getEndDate());
    pricingSchedule.setPricingType("PRICING_TYPE_CPM");
    pricingSchedule.setStartDate(campaign.getStartDate());
    placement.setPricingSchedule(pricingSchedule);
    
  3. 通过调用 placements.insert() 来保存该 Placement 对象。如果您要使用系统所返回的 ID 将该对象分配给 Ad 或 Creative,请务必妥善存储这个 ID。
    // Insert the placement.
    Placement result = reporting.placements().insert(profileId, placement).execute();
    

PHP

  1. 创建一个 Placement 对象,并设置必需的展示位置属性(包括 campaignIdsiteId)。此外,请务必根据您与网站之间的协商结果准确设置该展示位置的类型和尺寸。
    $placement = new Google_Service_Dfareporting_Placement();
    $placement->setCampaignId($values['campaign_id']);
    $placement->setCompatibility('DISPLAY');
    $placement->setName($values['placement_name']);
    $placement->setPaymentSource('PLACEMENT_AGENCY_PAID');
    $placement->setSiteId($values['site_id']);
    $placement->setTagFormats(['PLACEMENT_TAG_STANDARD']);
    
    // Set the size of the placement.
    $size = new Google_Service_Dfareporting_Size();
    $size->setId($values['size_id']);
    $placement->setSize($size);
    
  2. 创建一个新的 PricingSchedule 对象,以分配给该展示位置。
    // Set the pricing schedule for the placement.
    $pricingSchedule = new Google_Service_Dfareporting_PricingSchedule();
    $pricingSchedule->setEndDate($campaign->getEndDate());
    $pricingSchedule->setPricingType('PRICING_TYPE_CPM');
    $pricingSchedule->setStartDate($campaign->getStartDate());
    $placement->setPricingSchedule($pricingSchedule);
    
  3. 通过调用 placements.insert() 来保存该 Placement 对象。如果您要使用系统所返回的 ID 将该对象分配给 Ad 或 Creative,请务必妥善存储这个 ID。
    // Insert the placement.
    $result = $this->service->placements->insert(
        $values['user_profile_id'],
        $placement
    );
    

Python

  1. 创建一个 Placement 对象,并设置必需的展示位置属性(包括 campaignIdsiteId)。此外,请务必根据您与网站之间的协商结果准确设置该展示位置的类型和尺寸。
    # Construct and save placement.
    placement = {
        'name': 'Test Placement',
        'campaignId': campaign_id,
        'compatibility': 'DISPLAY',
        'siteId': site_id,
        'size': {
            'height': '1',
            'width': '1'
        },
        'paymentSource': 'PLACEMENT_AGENCY_PAID',
        'tagFormats': ['PLACEMENT_TAG_STANDARD']
    }
    
  2. 创建一个新的 PricingSchedule 对象,以分配给该展示位置。
    # Set the pricing schedule for the placement.
    placement['pricingSchedule'] = {
        'startDate': campaign['startDate'],
        'endDate': campaign['endDate'],
        'pricingType': 'PRICING_TYPE_CPM'
    }
    
  3. 通过调用 placements.insert() 来保存该 Placement 对象。如果您要使用系统所返回的 ID 将该对象分配给 Ad 或 Creative,请务必妥善存储这个 ID。
    request = service.placements().insert(profileId=profile_id, body=placement)
    
    # Execute request and print response.
    response = request.execute()
    

Ruby

  1. 创建一个 Placement 对象,并设置必需的展示位置属性(包括 campaignIdsiteId)。此外,请务必根据您与网站之间的协商结果准确设置该展示位置的类型和尺寸。
    # Create a new placement resource to insert.
    placement = DfareportingUtils::API_NAMESPACE::Placement.new(
      campaign_id: campaign_id,
      compatibility: 'DISPLAY',
      name: 'Example Placement',
      payment_source: 'PLACEMENT_AGENCY_PAID',
      site_id: site_id,
      size: DfareportingUtils::API_NAMESPACE::Size.new(
        height: 1,
        width: 1
      ),
      tag_formats: ['PLACEMENT_TAG_STANDARD']
    )
    
  2. 创建一个新的 PricingSchedule 对象,以分配给该展示位置。
    # Set the pricing schedule for the placement.
    placement.pricing_schedule =
      DfareportingUtils::API_NAMESPACE::PricingSchedule.new(
        end_date: campaign.end_date,
        pricing_type: 'PRICING_TYPE_CPM',
        start_date: campaign.start_date
      )
    
  3. 通过调用 placements.insert() 来保存该 Placement 对象。如果您要使用系统所返回的 ID 将该对象分配给 Ad 或 Creative,请务必妥善存储这个 ID。
    # Insert the placement strategy.
    result = service.insert_placement(profile_id, placement)
    

上传素材资源

您可以通过一种称为媒体上传的流程来上传多种类型的素材资源。尽管对于所有广告素材类型来说,这个流程都是相似的,但某些广告素材类型可能需要将特定属性作为元数据进行传递,才能正常使用这些属性。

C#

  1. 创建一个 assetIdentifier 对象,并设置必需的属性。您需要为所有素材资源(不论其类型或使用方式为何)都指定 assetIdentifier。当您将素材资源分配给广告素材时,该对象将用于回指相应素材资源。以下属性是必需的属性:

    • name 属性:素材资源将在服务器上使用的名称。该名称必须包含表示文件类型的扩展名(例如 .png 或 .gif),并将作为素材资源名称提供给浏览器,但该名称不必与原始文件名相同。请注意,Campaign Manager 360 可能会更改该名称,以确保其在服务器上是独一无二的;请检查返回值,看看它是否已被更改。
    • type 属性:用于标识素材资源的类型。该属性将决定素材资源可以与哪些类型的广告素材相关联。
    // Create the creative asset ID and Metadata.
    CreativeAssetId assetId = new CreativeAssetId();
    assetId.Name = Path.GetFileName(assetFile);
    assetId.Type = assetType;
    
  2. 通过调用 creativeAssets.insert() 来上传文件。执行多部分上传,通过同一项请求同时传递 assetIdentifier 和文件内容。如果上传成功,系统将会返回一个 CreativeAsset 资源,以及将该素材资源分配给广告素材时将使用的 assetIdentifier

    // Prepare an input stream.
    FileStream assetContent = new FileStream(assetFile, FileMode.Open, FileAccess.Read);
    
    CreativeAssetMetadata metaData = new CreativeAssetMetadata();
    metaData.AssetIdentifier = assetId;
    
    // Insert the creative.
    String mimeType = determineMimeType(assetFile, assetType);
    CreativeAssetsResource.InsertMediaUpload request =
        Service.CreativeAssets.Insert(metaData, ProfileId, AdvertiserId, assetContent, mimeType);
    
    IUploadProgress progress = request.Upload();
    if (UploadStatus.Failed.Equals(progress.Status)) {
        throw progress.Exception;
    }
    

Java

  1. 创建一个 assetIdentifier 对象,并设置必需的属性。您需要为所有素材资源(不论其类型或使用方式为何)都指定 assetIdentifier。当您将素材资源分配给广告素材时,该对象将用于回指相应素材资源。以下属性是必需的属性:

    • name 属性:素材资源将在服务器上使用的名称。该名称必须包含表示文件类型的扩展名(例如 .png 或 .gif),并将作为素材资源名称提供给浏览器,但该名称不必与原始文件名相同。请注意,Campaign Manager 360 可能会更改该名称,以确保其在服务器上是独一无二的;请检查返回值,看看它是否已被更改。
    • type 属性:用于标识素材资源的类型。该属性将决定素材资源可以与哪些类型的广告素材相关联。
    // Create the creative asset ID and Metadata.
    CreativeAssetId assetId = new CreativeAssetId();
    assetId.setName(assetName);
    assetId.setType(assetType);
    
  2. 通过调用 creativeAssets.insert() 来上传文件。执行多部分上传,通过同一项请求同时传递 assetIdentifier 和文件内容。如果上传成功,系统将会返回一个 CreativeAsset 资源,以及将该素材资源分配给广告素材时将使用的 assetIdentifier

    // Open the asset file.
    File file = new File(assetFile);
    
    // Prepare an input stream.
    String contentType = getMimeType(assetFile);
    InputStreamContent assetContent =
        new InputStreamContent(contentType, new BufferedInputStream(new FileInputStream(file)));
    assetContent.setLength(file.length());
    
    CreativeAssetMetadata metaData = new CreativeAssetMetadata();
    metaData.setAssetIdentifier(assetId);
    
    // Insert the creative.
    CreativeAssetMetadata result = reporting.creativeAssets()
        .insert(profileId, advertiserId, metaData, assetContent).execute();
    

PHP

  1. 创建一个 assetIdentifier 对象,并设置必需的属性。您需要为所有素材资源(不论其类型或使用方式为何)都指定 assetIdentifier。当您将素材资源分配给广告素材时,该对象将用于回指相应素材资源。以下属性是必需的属性:

    • name 属性:素材资源将在服务器上使用的名称。该名称必须包含表示文件类型的扩展名(例如 .png 或 .gif),并将作为素材资源名称提供给浏览器,但该名称不必与原始文件名相同。请注意,Campaign Manager 360 可能会更改该名称,以确保其在服务器上是独一无二的;请检查返回值,看看它是否已被更改。
    • type 属性:用于标识素材资源的类型。该属性将决定素材资源可以与哪些类型的广告素材相关联。
    $assetId = new Google_Service_Dfareporting_CreativeAssetId();
    $assetId->setName($asset['name']);
    $assetId->setType($type);
    
  2. 通过调用 creativeAssets.insert() 来上传文件。执行多部分上传,通过同一项请求同时传递 assetIdentifier 和文件内容。如果上传成功,系统将会返回一个 CreativeAsset 资源,以及将该素材资源分配给广告素材时将使用的 assetIdentifier

    $metadata = new Google_Service_Dfareporting_CreativeAssetMetadata();
    $metadata->setAssetIdentifier($assetId);
    
    $result = $service->creativeAssets->insert(
        $userProfileId,
        $advertiserId,
        $metadata,
        ['data' => file_get_contents($asset['tmp_name']),
         'mimeType' => $asset['type'],
         'uploadType' => 'multipart']
    );
    

Python

  1. 创建一个 assetIdentifier 对象,并设置必需的属性。您需要为所有素材资源(不论其类型或使用方式为何)都指定 assetIdentifier。当您将素材资源分配给广告素材时,该对象将用于回指相应素材资源。以下属性是必需的属性:

    • name 属性:素材资源将在服务器上使用的名称。该名称必须包含表示文件类型的扩展名(例如 .png 或 .gif),并将作为素材资源名称提供给浏览器,但该名称不必与原始文件名相同。请注意,Campaign Manager 360 可能会更改该名称,以确保其在服务器上是独一无二的;请检查返回值,看看它是否已被更改。
    • type 属性:用于标识素材资源的类型。该属性将决定素材资源可以与哪些类型的广告素材相关联。
    # Construct the creative asset metadata
    creative_asset = {'assetIdentifier': {'name': asset_name, 'type': asset_type}}
    
  2. 通过调用 creativeAssets.insert() 来上传文件。执行多部分上传,通过同一项请求同时传递 assetIdentifier 和文件内容。如果上传成功,系统将会返回一个 CreativeAsset 资源,以及将该素材资源分配给广告素材时将使用的 assetIdentifier

    media = MediaFileUpload(path_to_asset_file)
    if not media.mimetype():
      media = MediaFileUpload(path_to_asset_file, 'application/octet-stream')
    
    response = service.creativeAssets().insert(
        advertiserId=advertiser_id,
        profileId=profile_id,
        media_body=media,
        body=creative_asset).execute()
    

Ruby

  1. 创建一个 assetIdentifier 对象,并设置必需的属性。您需要为所有素材资源(不论其类型或使用方式为何)都指定 assetIdentifier。当您将素材资源分配给广告素材时,该对象将用于回指相应素材资源。以下属性是必需的属性:

    • name 属性:素材资源将在服务器上使用的名称。该名称必须包含表示文件类型的扩展名(例如 .png 或 .gif),并将作为素材资源名称提供给浏览器,但该名称不必与原始文件名相同。请注意,Campaign Manager 360 可能会更改该名称,以确保其在服务器上是独一无二的;请检查返回值,看看它是否已被更改。
    • type 属性:用于标识素材资源的类型。该属性将决定素材资源可以与哪些类型的广告素材相关联。
    # Construct the creative asset metadata
    creative_asset = DfareportingUtils::API_NAMESPACE::CreativeAsset.new(
      asset_identifier: DfareportingUtils::API_NAMESPACE::CreativeAssetId.new(
        name: asset_name,
        type: asset_type
      )
    )
    
  2. 通过调用 creativeAssets.insert() 来上传文件。执行多部分上传,通过同一项请求同时传递 assetIdentifier 和文件内容。如果上传成功,系统将会返回一个 CreativeAsset 资源,以及将该素材资源分配给广告素材时将使用的 assetIdentifier

    # Upload the asset.
    mime_type = determine_mime_type(path_to_asset_file, asset_type)
    
    result = @service.insert_creative_asset(
      @profile_id,
      advertiser_id,
      creative_asset,
      content_type: mime_type,
      upload_source: path_to_asset_file
    )
    

创建广告素材

Creative 对象用于封装现有素材资源。根据您在托管网页上对广告素材的使用方式,您可以创建不同广告素材类型的 Creative 对象。请参阅参考文档,确定哪种类型适合您。

以下示例展示了如何创建新的 HTML5 展示广告素材。

C#

  1. 上传素材资源。不同的广告素材需要不同类型和不同数量的素材资源;有关详情,请参阅上传素材资源。每次成功上传素材资源后,您都会在响应中收到一个 assetIdenfitier;您将需要使用存储的文件名和类型来引用您广告素材中的这些素材资源,而不是使用传统 ID。
  2. 创建一个广告素材并为其分配适当的值。将 Creative 实例化,并设置适当的 type;保存 Creative 对象后,您将无法更改其类型。请使用 AssetIdentifierrole 指定素材资源。
    // Locate an advertiser landing page to use as a default.
    LandingPage defaultLandingPage = getAdvertiserLandingPage(service, profileId, advertiserId);
    
    // Create the creative structure.
    Creative creative = new Creative();
    creative.AdvertiserId = advertiserId;
    creative.Name = "Test HTML5 display creative";
    creative.Size = new Size() { Id = sizeId };
    creative.Type = "DISPLAY";
    
    // Upload the HTML5 asset.
    CreativeAssetUtils assetUtils = new CreativeAssetUtils(service, profileId, advertiserId);
    CreativeAssetId html5AssetId =
        assetUtils.uploadAsset(pathToHtml5AssetFile, "HTML").AssetIdentifier;
    
    CreativeAsset html5Asset = new CreativeAsset();
    html5Asset.AssetIdentifier = html5AssetId;
    html5Asset.Role = "PRIMARY";
    
    // Upload the backup image asset.
    CreativeAssetId imageAssetId =
        assetUtils.uploadAsset(pathToImageAssetFile, "HTML_IMAGE").AssetIdentifier;
    
    CreativeAsset imageAsset = new CreativeAsset();
    imageAsset.AssetIdentifier = imageAssetId;
    imageAsset.Role = "BACKUP_IMAGE";
    
    // Add the creative assets.
    creative.CreativeAssets = new List<CreativeAsset>() { html5Asset, imageAsset };
    
    // Configure the bacup image.
    creative.BackupImageClickThroughUrl = new CreativeClickThroughUrl() {
      LandingPageId = defaultLandingPage.Id
    };
    creative.BackupImageReportingLabel = "backup";
    creative.BackupImageTargetWindow = new TargetWindow() { TargetWindowOption = "NEW_WINDOW" };
    
    // Add a click tag.
    ClickTag clickTag = new ClickTag();
    clickTag.Name = "clickTag";
    clickTag.EventName = "exit";
    clickTag.ClickThroughUrl = new CreativeClickThroughUrl() {
      LandingPageId = defaultLandingPage.Id
    };
    creative.ClickTags = new List<ClickTag>() { clickTag };
    
  3. 通过调用 creatives.insert() 来保存该广告素材。您必须指定一个广告客户 ID,以将其与该广告素材相关联。
    Creative result = service.Creatives.Insert(creative, profileId).Execute();
    
  4. (可选)将该广告素材与广告系列相关联。您可以通过调用 campaignCreativeAssociations.insert()(以传入广告系列 ID 和广告素材 ID)来完成此操作。
    // Create the campaign creative association structure.
    CampaignCreativeAssociation association = new CampaignCreativeAssociation();
    association.CreativeId = creativeId;
    
    // Insert the association.
    CampaignCreativeAssociation result =
        service.CampaignCreativeAssociations.Insert(association, profileId, campaignId).Execute();
    

Java

  1. 上传素材资源。不同的广告素材需要不同类型和不同数量的素材资源;有关详情,请参阅上传素材资源。每次成功上传素材资源后,您都会在响应中收到一个 assetIdenfitier;您将需要使用存储的文件名和类型来引用您广告素材中的这些素材资源,而不是使用传统 ID。
  2. 创建一个广告素材并为其分配适当的值。将 Creative 实例化,并设置适当的 type;保存 Creative 对象后,您将无法更改其类型。请使用 AssetIdentifierrole 指定素材资源。
    // Locate an advertiser landing page to use as a default.
    LandingPage defaultLandingPage = getAdvertiserLandingPage(reporting, profileId, advertiserId);
    
    // Create the creative structure.
    Creative creative = new Creative();
    creative.setAdvertiserId(advertiserId);
    creative.setName("Test HTML5 display creative");
    creative.setSize(new Size().setId(sizeId));
    creative.setType("DISPLAY");
    
    // Upload the HTML5 asset.
    CreativeAssetId html5AssetId = CreativeAssetUtils.uploadAsset(reporting, profileId,
        advertiserId, HTML5_ASSET_NAME, PATH_TO_HTML5_ASSET_FILE, "HTML").getAssetIdentifier();
    
    CreativeAsset html5Asset =
        new CreativeAsset().setAssetIdentifier(html5AssetId).setRole("PRIMARY");
    
    // Upload the backup image asset (note: asset type must be set to HTML_IMAGE).
    CreativeAssetId imageAssetId = CreativeAssetUtils.uploadAsset(reporting, profileId,
        advertiserId, IMAGE_ASSET_NAME, PATH_TO_IMAGE_ASSET_FILE, "HTML_IMAGE")
        .getAssetIdentifier();
    
    CreativeAsset backupImageAsset =
        new CreativeAsset().setAssetIdentifier(imageAssetId).setRole("BACKUP_IMAGE");
    
    // Add the creative assets.
    creative.setCreativeAssets(ImmutableList.of(html5Asset, backupImageAsset));
    
    // Configure the backup image.
    creative.setBackupImageClickThroughUrl(
        new CreativeClickThroughUrl().setLandingPageId(defaultLandingPage.getId()));
    creative.setBackupImageReportingLabel("backup");
    creative.setBackupImageTargetWindow(new TargetWindow().setTargetWindowOption("NEW_WINDOW"));
    
    // Add a click tag.
    ClickTag clickTag =
        new ClickTag().setName("clickTag").setEventName("exit").setClickThroughUrl(
            new CreativeClickThroughUrl().setLandingPageId(defaultLandingPage.getId()));
    creative.setClickTags(ImmutableList.of(clickTag));
    
  3. 通过调用 creatives.insert() 来保存该广告素材。您必须指定一个广告客户 ID,以将其与该广告素材相关联。
    Creative result = reporting.creatives().insert(profileId, creative).execute();
    
  4. (可选)将该广告素材与广告系列相关联。您可以通过调用 campaignCreativeAssociations.insert()(以传入广告系列 ID 和广告素材 ID)来完成此操作。
    // Create the campaign creative association structure.
    CampaignCreativeAssociation association = new CampaignCreativeAssociation();
    association.setCreativeId(creativeId);
    
    // Insert the association.
    CampaignCreativeAssociation result = reporting
        .campaignCreativeAssociations().insert(profileId, campaignId, association)
        .execute();
    

PHP

  1. 上传素材资源。不同的广告素材需要不同类型和不同数量的素材资源;有关详情,请参阅上传素材资源。每次成功上传素材资源后,您都会在响应中收到一个 assetIdenfitier;您将需要使用存储的文件名和类型来引用您广告素材中的这些素材资源,而不是使用传统 ID。
  2. 创建一个广告素材并为其分配适当的值。将 Creative 实例化,并设置适当的 type;保存 Creative 对象后,您将无法更改其类型。请使用 AssetIdentifierrole 指定素材资源。
    $creative = new Google_Service_Dfareporting_Creative();
    $creative->setAdvertiserId($values['advertiser_id']);
    $creative->setAutoAdvanceImages(true);
    $creative->setName('Test HTML5 display creative');
    $creative->setType('DISPLAY');
    
    $size = new Google_Service_Dfareporting_Size();
    $size->setId($values['size_id']);
    $creative->setSize($size);
    
    // Upload the HTML5 asset.
    $html = uploadAsset(
        $this->service,
        $values['user_profile_id'],
        $values['advertiser_id'],
        $values['html_asset_file'],
        'HTML'
    );
    
    $htmlAsset = new Google_Service_Dfareporting_CreativeAsset();
    $htmlAsset->setAssetIdentifier($html->getAssetIdentifier());
    $htmlAsset->setRole('PRIMARY');
    
    // Upload the backup image asset.
    $image = uploadAsset(
        $this->service,
        $values['user_profile_id'],
        $values['advertiser_id'],
        $values['image_asset_file'],
        'HTML_IMAGE'
    );
    
    $imageAsset = new Google_Service_Dfareporting_CreativeAsset();
    $imageAsset->setAssetIdentifier($image->getAssetIdentifier());
    $imageAsset->setRole('BACKUP_IMAGE');
    
    // Add the creative assets.
    $creative->setCreativeAssets([$htmlAsset, $imageAsset]);
    
    // Configure the default click-through URL.
    $clickThroughUrl =
        new Google_Service_Dfareporting_CreativeClickThroughUrl();
    $clickThroughUrl->setLandingPageId($values['landing_page_id']);
    
    // Configure the backup image.
    $creative->setBackupImageClickThroughUrl($clickThroughUrl);
    $creative->setBackupImageReportingLabel('backup');
    
    $targetWindow = new Google_Service_Dfareporting_TargetWindow();
    $targetWindow->setTargetWindowOption('NEW_WINDOW');
    $creative->setBackupImageTargetWindow($targetWindow);
    
    // Add a click tag.
    $clickTag = new Google_Service_Dfareporting_ClickTag();
    $clickTag->setName('clickTag');
    $clickTag->setEventName('exit');
    $clickTag->setClickThroughUrl($clickThroughUrl);
    $creative->setClickTags([$clickTag]);
    
  3. 通过调用 creatives.insert() 来保存该广告素材。您必须指定一个广告客户 ID,以将其与该广告素材相关联。
    $result = $this->service->creatives->insert(
        $values['user_profile_id'],
        $creative
    );
    
  4. (可选)将该广告素材与广告系列相关联。您可以通过调用 campaignCreativeAssociations.insert()(以传入广告系列 ID 和广告素材 ID)来完成此操作。
    $association =
        new Google_Service_Dfareporting_CampaignCreativeAssociation();
    $association->setCreativeId($values['creative_id']);
    
    $result = $this->service->campaignCreativeAssociations->insert(
        $values['user_profile_id'],
        $values['campaign_id'],
        $association
    );
    

Python

  1. 上传素材资源。不同的广告素材需要不同类型和不同数量的素材资源;有关详情,请参阅上传素材资源。每次成功上传素材资源后,您都会在响应中收到一个 assetIdenfitier;您将需要使用存储的文件名和类型来引用您广告素材中的这些素材资源,而不是使用传统 ID。
  2. 创建一个广告素材并为其分配适当的值。将 Creative 实例化,并设置适当的 type;保存 Creative 对象后,您将无法更改其类型。请使用 AssetIdentifierrole 指定素材资源。
    # Locate an advertiser landing page to use as a default.
    default_landing_page = get_advertiser_landing_page(service, profile_id,
                                                       advertiser_id)
    
    # Upload the HTML5 asset
    html5_asset_id = upload_creative_asset(service, profile_id, advertiser_id,
                                           html5_asset_name,
                                           path_to_html5_asset_file, 'HTML')
    
    # Upload the backup image asset
    backup_image_asset_id = upload_creative_asset(
        service, profile_id, advertiser_id, backup_image_name,
        path_to_backup_image_file, 'HTML_IMAGE')
    
    # Construct the creative structure.
    creative = {
        'advertiserId': advertiser_id,
        'backupImageClickThroughUrl': {
            'landingPageId': default_landing_page['id']
        },
        'backupImageReportingLabel': 'backup_image_exit',
        'backupImageTargetWindow': {'targetWindowOption': 'NEW_WINDOW'},
        'clickTags': [{
            'eventName': 'exit',
            'name': 'click_tag',
            'clickThroughUrl': {'landingPageId': default_landing_page['id']}
        }],
        'creativeAssets': [
            {'assetIdentifier': html5_asset_id, 'role': 'PRIMARY'},
            {'assetIdentifier': backup_image_asset_id, 'role': 'BACKUP_IMAGE'}
        ],
        'name': 'Test HTML5 display creative',
        'size': {'id': size_id},
        'type': 'DISPLAY'
    }
    
  3. 通过调用 creatives.insert() 来保存该广告素材。您必须指定一个广告客户 ID,以将其与该广告素材相关联。
    request = service.creatives().insert(profileId=profile_id, body=creative)
    
    # Execute request and print response.
    response = request.execute()
    
  4. (可选)将该广告素材与广告系列相关联。您可以通过调用 campaignCreativeAssociations.insert()(以传入广告系列 ID 和广告素材 ID)来完成此操作。
    # Construct the request.
    association = {
        'creativeId': creative_id
    }
    
    request = service.campaignCreativeAssociations().insert(
        profileId=profile_id, campaignId=campaign_id, body=association)
    
    # Execute request and print response.
    response = request.execute()
    

Ruby

  1. 上传素材资源。不同的广告素材需要不同类型和不同数量的素材资源;有关详情,请参阅上传素材资源。每次成功上传素材资源后,您都会在响应中收到一个 assetIdenfitier;您将需要使用存储的文件名和类型来引用您广告素材中的这些素材资源,而不是使用传统 ID。
  2. 创建一个广告素材并为其分配适当的值。将 Creative 实例化,并设置适当的 type;保存 Creative 对象后,您将无法更改其类型。请使用 AssetIdentifierrole 指定素材资源。
    # Locate an advertiser landing page to use as a default.
    default_landing_page = get_advertiser_landing_page(service, profile_id,
      advertiser_id)
    
    # Upload the HTML5 asset.
    html5_asset_id = util.upload_asset(advertiser_id, path_to_html5_asset_file,
      'HTML').asset_identifier
    
    # Upload the backup image asset.
    backup_image_asset_id = util.upload_asset(advertiser_id,
      path_to_backup_image_file, 'HTML_IMAGE').asset_identifier
    
    # Construct the creative structure.
    creative = DfareportingUtils::API_NAMESPACE::Creative.new(
      advertiser_id: advertiser_id,
      backup_image_click_through_url:
        DfareportingUtils::API_NAMESPACE::CreativeClickThroughUrl.new(
          landing_page_id: default_landing_page.id
        ),
      backup_image_reporting_label: 'backup',
      backup_image_target_window:
        DfareportingUtils::API_NAMESPACE::TargetWindow.new(
          target_window_option: 'NEW_WINDOW'
        ),
      click_tags: [
        DfareportingUtils::API_NAMESPACE::ClickTag.new(
          event_name: 'exit',
          name: 'click_tag',
          click_through_url:
            DfareportingUtils::API_NAMESPACE::CreativeClickThroughUrl.new(
              landing_page_id: default_landing_page.id
            )
        )
      ],
      creative_assets: [
        DfareportingUtils::API_NAMESPACE::CreativeAsset.new(
          asset_identifier: html5_asset_id,
          role: 'PRIMARY'
        ),
        DfareportingUtils::API_NAMESPACE::CreativeAsset.new(
          asset_identifier: backup_image_asset_id,
          role: 'BACKUP_IMAGE'
        )
      ],
      name: 'Example HTML5 display creative',
      size: DfareportingUtils::API_NAMESPACE::Size.new(id: size_id),
      type: 'DISPLAY'
    )
    
  3. 通过调用 creatives.insert() 来保存该广告素材。您必须指定一个广告客户 ID,以将其与该广告素材相关联。
    # Insert the creative.
    result = service.insert_creative(profile_id, creative)
    
  4. (可选)将该广告素材与广告系列相关联。您可以通过调用 campaignCreativeAssociations.insert()(以传入广告系列 ID 和广告素材 ID)来完成此操作。
    # Create a new creative-campaign association to insert
    association =
      DfareportingUtils::API_NAMESPACE::CampaignCreativeAssociation.new(
        creative_id: creative_id
      )
    
    # Insert the advertiser group.
    result = service.insert_campaign_creative_association(profile_id, campaign_id,
      association)
    

创建广告

Ad 是将 CreativePlacement 联系起来的纽带。一个 Ad 可以与一个或多个展示位置相关联,而且可以包含一个或多个广告素材。

您可以通过显式方式或隐式方式创建 Ad

通过显式方式创建

C#

  1. 针对每个应该与要创建的广告关联的广告素材,分别创建一个 CreativeAssignment 对象。请务必将 CreativeAssignment.active 字段设为 true。
    // Create a click-through URL.
    ClickThroughUrl clickThroughUrl = new ClickThroughUrl();
    clickThroughUrl.DefaultLandingPage = true;
    
    // Create a creative assignment.
    CreativeAssignment creativeAssignment = new CreativeAssignment();
    creativeAssignment.Active = true;
    creativeAssignment.CreativeId = creativeId;
    creativeAssignment.ClickThroughUrl = clickThroughUrl;
    
  2. 创建一个 CreativeRotation 对象来储存 CreativeAssignment。如果创建的是轮播组,请务必设置其他必填的广告素材轮播字段。
    // Create a creative rotation.
    CreativeRotation creativeRotation = new CreativeRotation();
    creativeRotation.CreativeAssignments = new List<CreativeAssignment>() {
        creativeAssignment
    };
    
  3. 针对每个应该与要创建的广告关联的展示位置,分别创建一个 PlacementAssignment 对象。请务必将 PlacementAssignment.active 字段设为 true。
    // Create a placement assignment.
    PlacementAssignment placementAssignment = new PlacementAssignment();
    placementAssignment.Active = true;
    placementAssignment.PlacementId = placementId;
    
  4. 创建一个 Ad 对象。在 Ad 对象的 creativeRotation 字段中设置 creativeRotation,并在 Ad 对象的 placementAssignments 数组中设置 placementAssignments。
    // Create a delivery schedule.
    DeliverySchedule deliverySchedule = new DeliverySchedule();
    deliverySchedule.ImpressionRatio = 1;
    deliverySchedule.Priority = "AD_PRIORITY_01";
    
    DateTime startDate = DateTime.Now;
    DateTime endDate = Convert.ToDateTime(campaign.EndDate);
    
    // Create a rotation group.
    Ad rotationGroup = new Ad();
    rotationGroup.Active = true;
    rotationGroup.CampaignId = campaignId;
    rotationGroup.CreativeRotation = creativeRotation;
    rotationGroup.DeliverySchedule = deliverySchedule;
    rotationGroup.StartTime = startDate;
    rotationGroup.EndTime = endDate;
    rotationGroup.Name = adName;
    rotationGroup.PlacementAssignments = new List<PlacementAssignment>() {
        placementAssignment
    };
    rotationGroup.Type = "AD_SERVING_STANDARD_AD";
    
  5. 通过调用 ads.insert() 来保存该广告。
    // Insert the rotation group.
    Ad result = service.Ads.Insert(rotationGroup, profileId).Execute();
    

Java

  1. 针对每个应该与要创建的广告关联的广告素材,分别创建一个 CreativeAssignment 对象。请务必将 CreativeAssignment.active 字段设为 true。
    // Create a click-through URL.
    ClickThroughUrl clickThroughUrl = new ClickThroughUrl();
    clickThroughUrl.setDefaultLandingPage(true);
    
    // Create a creative assignment.
    CreativeAssignment creativeAssignment = new CreativeAssignment();
    creativeAssignment.setActive(true);
    creativeAssignment.setCreativeId(creativeId);
    creativeAssignment.setClickThroughUrl(clickThroughUrl);
    
  2. 创建一个 CreativeRotation 对象来储存 CreativeAssignment。如果创建的是轮播组,请务必设置其他必填的广告素材轮播字段。
    // Create a creative rotation.
    CreativeRotation creativeRotation = new CreativeRotation();
    creativeRotation.setCreativeAssignments(ImmutableList.of(creativeAssignment));
    
  3. 针对每个应该与要创建的广告关联的展示位置,分别创建一个 PlacementAssignment 对象。请务必将 PlacementAssignment.active 字段设为 true。
    // Create a placement assignment.
    PlacementAssignment placementAssignment = new PlacementAssignment();
    placementAssignment.setActive(true);
    placementAssignment.setPlacementId(placementId);
    
  4. 创建一个 Ad 对象。在 Ad 对象的 creativeRotation 字段中设置 creativeRotation,并在 Ad 对象的 placementAssignments 数组中设置 placementAssignments。
    // Create a delivery schedule.
    DeliverySchedule deliverySchedule = new DeliverySchedule();
    deliverySchedule.setImpressionRatio(1L);
    deliverySchedule.setPriority("AD_PRIORITY_01");
    
    DateTime startDate = new DateTime(new Date());
    DateTime endDate = campaign.getEndDate();
    
    // Create a rotation group.
    Ad rotationGroup = new Ad();
    rotationGroup.setActive(true);
    rotationGroup.setCampaignId(campaignId);
    rotationGroup.setCreativeRotation(creativeRotation);
    rotationGroup.setDeliverySchedule(deliverySchedule);
    rotationGroup.setStartTime(startDate);
    rotationGroup.setEndTime(endDate);
    rotationGroup.setName(adName);
    rotationGroup.setPlacementAssignments(ImmutableList.of(placementAssignment));
    rotationGroup.setType("AD_SERVING_STANDARD_AD");
    
  5. 通过调用 ads.insert() 来保存该广告。
    // Insert the rotation group.
    Ad result = reporting.ads().insert(profileId, rotationGroup).execute();
    

PHP

  1. 针对每个应该与要创建的广告关联的广告素材,分别创建一个 CreativeAssignment 对象。请务必将 CreativeAssignment.active 字段设为 true。
    // Create a click-through URL.
    $url = new Google_Service_Dfareporting_ClickThroughUrl();
    $url->setDefaultLandingPage(true);
    
    // Create a creative assignment.
    $creativeAssignment =
        new Google_Service_Dfareporting_CreativeAssignment();
    $creativeAssignment->setActive(true);
    $creativeAssignment->setCreativeId($values['creative_id']);
    $creativeAssignment->setClickThroughUrl($url);
    
  2. 创建一个 CreativeRotation 对象来储存 CreativeAssignment。如果创建的是轮播组,请务必设置其他必填的广告素材轮播字段。
    // Create a creative rotation.
    $creativeRotation = new Google_Service_Dfareporting_CreativeRotation();
    $creativeRotation->setCreativeAssignments([$creativeAssignment]);
    
  3. 针对每个应该与要创建的广告关联的展示位置,分别创建一个 PlacementAssignment 对象。请务必将 PlacementAssignment.active 字段设为 true。
    // Create a placement assignment.
    $placementAssignment =
        new Google_Service_Dfareporting_PlacementAssignment();
    $placementAssignment->setActive(true);
    $placementAssignment->setPlacementId($values['placement_id']);
    
  4. 创建一个 Ad 对象。在 Ad 对象的 creativeRotation 字段中设置 creativeRotation,并在 Ad 对象的 placementAssignments 数组中设置 placementAssignments。
    // Create a delivery schedule.
    $deliverySchedule = new Google_Service_Dfareporting_DeliverySchedule();
    $deliverySchedule->setImpressionRatio(1);
    $deliverySchedule->SetPriority('AD_PRIORITY_01');
    
    $startDate = new DateTime('today');
    $endDate = new DateTime($campaign->getEndDate());
    
    // Create a rotation group.
    $ad = new Google_Service_Dfareporting_Ad();
    $ad->setActive(true);
    $ad->setCampaignId($values['campaign_id']);
    $ad->setCreativeRotation($creativeRotation);
    $ad->setDeliverySchedule($deliverySchedule);
    $ad->setStartTime($startDate->format('Y-m-d') . 'T23:59:59Z');
    $ad->setEndTime($endDate->format('Y-m-d') . 'T00:00:00Z');
    $ad->setName($values['ad_name']);
    $ad->setPlacementAssignments([$placementAssignment]);
    $ad->setType('AD_SERVING_STANDARD_AD');
    
  5. 通过调用 ads.insert() 来保存该广告。
    $result = $this->service->ads->insert($values['user_profile_id'], $ad);
    

Python

  1. 针对每个应该与要创建的广告关联的广告素材,分别创建一个 CreativeAssignment 对象。请务必将 CreativeAssignment.active 字段设为 true。
    # Construct creative assignment.
    creative_assignment = {
        'active': 'true',
        'creativeId': creative_id,
        'clickThroughUrl': {
            'defaultLandingPage': 'true'
        }
    }
    
  2. 创建一个 CreativeRotation 对象来储存 CreativeAssignment。如果创建的是轮播组,请务必设置其他必填的广告素材轮播字段。
    # Construct creative rotation.
    creative_rotation = {
        'creativeAssignments': [creative_assignment],
        'type': 'CREATIVE_ROTATION_TYPE_RANDOM',
        'weightCalculationStrategy': 'WEIGHT_STRATEGY_OPTIMIZED'
    }
    
  3. 针对每个应该与要创建的广告关联的展示位置,分别创建一个 PlacementAssignment 对象。请务必将 PlacementAssignment.active 字段设为 true。
    # Construct placement assignment.
    placement_assignment = {
        'active': 'true',
        'placementId': placement_id,
    }
    
  4. 创建一个 Ad 对象。在 Ad 对象的 creativeRotation 字段中设置 creativeRotation,并在 Ad 对象的 placementAssignments 数组中设置 placementAssignments。
    # Construct delivery schedule.
    delivery_schedule = {
        'impressionRatio': '1',
        'priority': 'AD_PRIORITY_01'
    }
    
    # Construct and save ad.
    ad = {
        'active': 'true',
        'campaignId': campaign_id,
        'creativeRotation': creative_rotation,
        'deliverySchedule': delivery_schedule,
        'endTime': '%sT00:00:00Z' % campaign['endDate'],
        'name': 'Test Rotation Group',
        'placementAssignments': [placement_assignment],
        'startTime': '%sT23:59:59Z' % time.strftime('%Y-%m-%d'),
        'type': 'AD_SERVING_STANDARD_AD'
    }
    
  5. 通过调用 ads.insert() 来保存该广告。
    request = service.ads().insert(profileId=profile_id, body=ad)
    
    # Execute request and print response.
    response = request.execute()
    

Ruby

  1. 针对每个应该与要创建的广告关联的广告素材,分别创建一个 CreativeAssignment 对象。请务必将 CreativeAssignment.active 字段设为 true。
    # Construct creative assignment.
    creative_assignment =
      DfareportingUtils::API_NAMESPACE::CreativeAssignment.new(
        active: true,
        creative_id: creative_id,
        click_through_url: DfareportingUtils::API_NAMESPACE::ClickThroughUrl.new(
          default_landing_page: true
        )
      )
    
  2. 创建一个 CreativeRotation 对象来储存 CreativeAssignment。如果创建的是轮播组,请务必设置其他必填的广告素材轮播字段。
    # Construct creative rotation.
    creative_rotation = DfareportingUtils::API_NAMESPACE::CreativeRotation.new(
      creative_assignments: [creative_assignment],
      type: 'CREATIVE_ROTATION_TYPE_RANDOM',
      weight_calculation_strategy: 'WEIGHT_STRATEGY_OPTIMIZED'
    )
    
  3. 针对每个应该与要创建的广告关联的展示位置,分别创建一个 PlacementAssignment 对象。请务必将 PlacementAssignment.active 字段设为 true。
    # Construct placement assignment.
    placement_assignment =
      DfareportingUtils::API_NAMESPACE::PlacementAssignment.new(
        active: true,
        placement_id: placement_id
      )
    
  4. 创建一个 Ad 对象。在 Ad 对象的 creativeRotation 字段中设置 creativeRotation,并在 Ad 对象的 placementAssignments 数组中设置 placementAssignments。
    # Construct delivery schedule.
    delivery_schedule = DfareportingUtils::API_NAMESPACE::DeliverySchedule.new(
      impression_ratio: 1,
      priority: 'AD_PRIORITY_01'
    )
    
    # Construct and save ad.
    ad = DfareportingUtils::API_NAMESPACE::Ad.new(
      active: true,
      campaign_id: campaign_id,
      creative_rotation: creative_rotation,
      delivery_schedule: delivery_schedule,
      end_time: format('%sT00:00:00Z', campaign.end_date),
      name: 'Example Rotation Group',
      placement_assignments: [placement_assignment],
      start_time: format('%sT23:59:59Z', Time.now.strftime('%Y-%m-%d')),
      type: 'AD_SERVING_STANDARD_AD'
    )
    
  5. 通过调用 ads.insert() 来保存该广告。
    result = service.insert_ad(profile_id, ad)
    

通过隐式方式创建

C#

  1. 创建一个 Placement 并保存。
  2. 创建一个 Creative 并保存。
  3. 通过调用 campaignCreativeAssociations.insert(),将刚创建的 Creative 与用于刚创建的 Placement 的同一个 Campaign 相关联(请参阅创建广告素材部分中的第 4 步)。这会创建一个同时与刚创建的广告素材和展示位置关联的默认广告
    // Create the campaign creative association structure.
    CampaignCreativeAssociation association = new CampaignCreativeAssociation();
    association.CreativeId = creativeId;
    
    // Insert the association.
    CampaignCreativeAssociation result =
        service.CampaignCreativeAssociations.Insert(association, profileId, campaignId).Execute();
    

Java

  1. 创建一个 Placement 并保存。
  2. 创建一个 Creative 并保存。
  3. 通过调用 campaignCreativeAssociations.insert(),将刚创建的 Creative 与用于刚创建的 Placement 的同一个 Campaign 相关联(请参阅创建广告素材部分中的第 4 步)。这会创建一个同时与刚创建的广告素材和展示位置关联的默认广告
    // Create the campaign creative association structure.
    CampaignCreativeAssociation association = new CampaignCreativeAssociation();
    association.setCreativeId(creativeId);
    
    // Insert the association.
    CampaignCreativeAssociation result = reporting
        .campaignCreativeAssociations().insert(profileId, campaignId, association)
        .execute();
    

PHP

  1. 创建一个 Placement 并保存。
  2. 创建一个 Creative 并保存。
  3. 通过调用 campaignCreativeAssociations.insert(),将刚创建的 Creative 与用于刚创建的 Placement 的同一个 Campaign 相关联(请参阅创建广告素材部分中的第 4 步)。这会创建一个同时与刚创建的广告素材和展示位置关联的默认广告
    $association =
        new Google_Service_Dfareporting_CampaignCreativeAssociation();
    $association->setCreativeId($values['creative_id']);
    
    $result = $this->service->campaignCreativeAssociations->insert(
        $values['user_profile_id'],
        $values['campaign_id'],
        $association
    );
    

Python

  1. 创建一个 Placement 并保存。
  2. 创建一个 Creative 并保存。
  3. 通过调用 campaignCreativeAssociations.insert(),将刚创建的 Creative 与用于刚创建的 Placement 的同一个 Campaign 相关联(请参阅创建广告素材部分中的第 4 步)。这会创建一个同时与刚创建的广告素材和展示位置关联的默认广告
    # Construct the request.
    association = {
        'creativeId': creative_id
    }
    
    request = service.campaignCreativeAssociations().insert(
        profileId=profile_id, campaignId=campaign_id, body=association)
    
    # Execute request and print response.
    response = request.execute()
    

Ruby

  1. 创建一个 Placement 并保存。
  2. 创建一个 Creative 并保存。
  3. 通过调用 campaignCreativeAssociations.insert(),将刚创建的 Creative 与用于刚创建的 Placement 的同一个 Campaign 相关联(请参阅创建广告素材部分中的第 4 步)。这会创建一个同时与刚创建的广告素材和展示位置关联的默认广告
    # Create a new creative-campaign association to insert
    association =
      DfareportingUtils::API_NAMESPACE::CampaignCreativeAssociation.new(
        creative_id: creative_id
      )
    
    # Insert the advertiser group.
    result = service.insert_campaign_creative_association(profile_id, campaign_id,
      association)
    

通过隐式方式创建广告可以省去创建 Ad 的额外步骤。请注意,只有当您的广告系列中不存在任何具有指定尺寸的默认广告时,您才能这样做。

搜索对象

您可以通过以下方式搜索对象:调用由界定目标对象的服务提供的 list() 操作,并指定适合该对象类型的可选条件。例如,要搜索 Ad 对象,您应该调用 ads.list()。可选条件提供了一组适合相应对象的属性;您可以填写任意多个要作为搜索依据的属性。搜索操作将仅返回符合所有条件的对象;您不能执行只要求符合任一条件的搜索。字符串支持 * 通配符、不区分大小写,并且会与包含它的字符串相匹配。

您可以使用 fields 参数请求返回部分响应来提升搜索性能。此参数会指示服务器仅返回您指定的字段,而不是完整地显示所有相关资源。如需关于此主题的更多信息,请参阅性能提示指南。

分页

有时,针对一个 list() 请求检索所有结果的做法并不可取。例如,在成千上万个广告中,您可能只对 10 个最新的广告感兴趣。为此,许多 list() 方法都允许通过一个称作分页的流程请求返回较少的结果。

支持分页的方法会按“页”分组返回结果的子集。每个结果页上的结果最多为 1000 条(默认值)。您可以通过设置 maxResults 来更改每个结果页中显示的结果条数,还可以使用响应中返回的 nextPageToken 遍历所有结果页。

C#

// Limit the fields returned.
String fields = "nextPageToken,ads(advertiserId,id,name)";

AdsListResponse result;
String nextPageToken = null;

do {
  // Create and execute the ad list request.
  AdsResource.ListRequest request = service.Ads.List(profileId);
  request.Active = true;
  request.Fields = fields;
  request.PageToken = nextPageToken;
  result = request.Execute();

  foreach (Ad ad in result.Ads) {
    Console.WriteLine(
        "Ad with ID {0} and name \"{1}\" is associated with advertiser" +
        " ID {2}.", ad.Id, ad.Name, ad.AdvertiserId);
  }

  // Update the next page token.
  nextPageToken = result.NextPageToken;
} while (result.Ads.Any() && !String.IsNullOrEmpty(nextPageToken));

Java

// Limit the fields returned.
String fields = "nextPageToken,ads(advertiserId,id,name)";

AdsListResponse result;
String nextPageToken = null;

do {
  // Create and execute the ad list request.
  result = reporting.ads().list(profileId).setActive(true).setFields(fields)
      .setPageToken(nextPageToken).execute();

  for (Ad ad : result.getAds()) {
    System.out.printf(
        "Ad with ID %d and name \"%s\" is associated with advertiser ID %d.%n", ad.getId(),
        ad.getName(), ad.getAdvertiserId());
  }

  // Update the next page token.
  nextPageToken = result.getNextPageToken();
} while (!result.getAds().isEmpty() && !Strings.isNullOrEmpty(nextPageToken));

PHP

$response = null;
$pageToken = null;

do {
    // Create and execute the ads list request.
    $response = $this->service->ads->listAds(
        $values['user_profile_id'],
        ['active' => true, 'pageToken' => $pageToken]
    );

    foreach ($response->getAds() as $ads) {
        $this->printResultsTableRow($ads);
    }

    // Update the next page token.
    $pageToken = $response->getNextPageToken();
} while (!empty($response->getAds()) && !empty($pageToken));

Python

# Construct the request.
request = service.ads().list(profileId=profile_id, active=True)

while True:
  # Execute request and print response.
  response = request.execute()

  for ad in response['ads']:
    print 'Found ad with ID %s and name "%s".' % (ad['id'], ad['name'])

  if response['ads'] and response['nextPageToken']:
    request = service.ads().list_next(request, response)
  else:
    break

Ruby

token = nil
loop do
  result = service.list_ads(profile_id,
    page_token: token,
    fields: 'nextPageToken,ads(id,name)')

  # Display results.
  if result.ads.any?
    result.ads.each do |ad|
      puts format('Found ad with ID %d and name "%s".', ad.id, ad.name)
    end

    token = result.next_page_token
  else
    # Stop paging if there are no more results.
    token = nil
  end

  break if token.to_s.empty?
end

生成 Floodlight 代码

Floodlight 代码是嵌入到网页中的 HTML 代码,用于跟踪用户在网站中执行的操作(例如购物)。若要生成 Floodlight 代码,您需要一个属于 FloodlightActivityGroupFloodlightActivity

C#

  1. 创建一个新的 Floodlight 活动组,从而传入 nametypefloodlightConfigurationId 的值。
    // Create the floodlight activity group.
    FloodlightActivityGroup floodlightActivityGroup = new FloodlightActivityGroup();
    floodlightActivityGroup.Name = groupName;
    floodlightActivityGroup.FloodlightConfigurationId = floodlightConfigurationId;
    floodlightActivityGroup.Type = "COUNTER";
    
  2. 通过调用 floodlightActivityGroups.insert()(该方法会返回新活动组的 ID)来保存该 Floodlight 活动组。
    // Insert the activity group.
    FloodlightActivityGroup result =
        service.FloodlightActivityGroups.Insert(floodlightActivityGroup, profileId).Execute();
    
  3. 创建一个新的 Floodlight 活动,并为其分配您刚刚创建的 Floodlightand 活动组的 ID,以及所有其他必填字段。
    // Set floodlight activity structure.
    FloodlightActivity activity = new FloodlightActivity();
    activity.CountingMethod = "STANDARD_COUNTING";
    activity.Name = activityName;
    activity.FloodlightActivityGroupId = activityGroupId;
    activity.FloodlightTagType = "GLOBAL_SITE_TAG";
    activity.ExpectedUrl = url;
    
  4. 通过调用 floodlightActivities.insert()(该方法会返回新创建的活动的 ID)来保存新创建的活动。
    // Create the floodlight tag activity.
    FloodlightActivity result =
        service.FloodlightActivities.Insert(activity, profileId).Execute();
    
  5. 通过调用 floodlightActivities.generatetag() 并提供新创建的活动的 floodlightActivityId 来生成代码。然后,将这些代码发送给广告客户的网站站长。
    // Generate the floodlight activity tag.
    FloodlightActivitiesResource.GeneratetagRequest request =
        service.FloodlightActivities.Generatetag(profileId);
    request.FloodlightActivityId = activityId;
    
    FloodlightActivitiesGenerateTagResponse response = request.Execute();
    

Java

  1. 创建一个新的 Floodlight 活动组,从而传入 nametypefloodlightConfigurationId 的值。
    // Create the floodlight activity group.
    FloodlightActivityGroup floodlightActivityGroup = new FloodlightActivityGroup();
    floodlightActivityGroup.setName(groupName);
    floodlightActivityGroup.setFloodlightConfigurationId(floodlightConfigurationId);
    floodlightActivityGroup.setType("COUNTER");
    
  2. 通过调用 floodlightActivityGroups.insert()(该方法会返回新活动组的 ID)来保存该 Floodlight 活动组。
    // Insert the activity group.
    FloodlightActivityGroup result =
        reporting.floodlightActivityGroups().insert(profileId, floodlightActivityGroup).execute();
    
  3. 创建一个新的 Floodlight 活动,并为其分配您刚刚创建的 Floodlightand 活动组的 ID,以及所有其他必填字段。
    // Set floodlight activity structure.
    FloodlightActivity activity = new FloodlightActivity();
    activity.setName(activityName);
    activity.setCountingMethod("STANDARD_COUNTING");
    activity.setExpectedUrl(url);
    activity.setFloodlightActivityGroupId(activityGroupId);
    activity.setFloodlightTagType("GLOBAL_SITE_TAG");
    
  4. 通过调用 floodlightActivities.insert()(该方法会返回新创建的活动的 ID)来保存新创建的活动。
    // Create the floodlight tag activity.
    FloodlightActivity result =
        reporting.floodlightActivities().insert(profileId, activity).execute();
    
  5. 通过调用 floodlightActivities.generatetag() 并提供新创建的活动的 floodlightActivityId 来生成代码。然后,将这些代码发送给广告客户的网站站长。
    // Generate the floodlight activity tag.
    Generatetag request = reporting.floodlightActivities().generatetag(profileId);
    request.setFloodlightActivityId(activityId);
    
    FloodlightActivitiesGenerateTagResponse response = request.execute();
    

PHP

  1. 创建一个新的 Floodlight 活动组,从而传入 nametypefloodlightConfigurationId 的值。
    $group = new Google_Service_Dfareporting_FloodlightActivityGroup();
    $group->setFloodlightConfigurationId($values['configuration_id']);
    $group->setName($values['group_name']);
    $group->setType('COUNTER');
    
  2. 通过调用 floodlightActivityGroups.insert()(该方法会返回新活动组的 ID)来保存该 Floodlight 活动组。
    $result = $this->service->floodlightActivityGroups->insert(
        $values['user_profile_id'],
        $group
    );
    
  3. 创建一个新的 Floodlight 活动,并为其分配您刚刚创建的 Floodlightand 活动组的 ID,以及所有其他必填字段。
    $activity = new Google_Service_Dfareporting_FloodlightActivity();
    $activity->setCountingMethod('STANDARD_COUNTING');
    $activity->setExpectedUrl($values['url']);
    $activity->setFloodlightActivityGroupId($values['activity_group_id']);
    $activity->setFloodlightTagType('GLOBAL_SITE_TAG');
    $activity->setName($values['activity_name']);
    
  4. 通过调用 floodlightActivities.insert()(该方法会返回新创建的活动的 ID)来保存新创建的活动。
    $result = $this->service->floodlightActivities->insert(
        $values['user_profile_id'],
        $activity
    );
    
  5. 通过调用 floodlightActivities.generatetag() 并提供新创建的活动的 floodlightActivityId 来生成代码。然后,将这些代码发送给广告客户的网站站长。
    $result = $this->service->floodlightActivities->generatetag(
        $values['user_profile_id'],
        ['floodlightActivityId' => $values['activity_id']]
    );
    

Python

  1. 创建一个新的 Floodlight 活动组,从而传入 nametypefloodlightConfigurationId 的值。
    # Construct and save floodlight activity group.
    activity_group = {
        'name': 'Test Floodlight Activity Group',
        'floodlightConfigurationId': floodlight_config_id,
        'type': 'COUNTER'
    }
    
  2. 通过调用 floodlightActivityGroups.insert()(该方法会返回新活动组的 ID)来保存该 Floodlight 活动组。
    request = service.floodlightActivityGroups().insert(
        profileId=profile_id, body=activity_group)
    
  3. 创建一个新的 Floodlight 活动,并为其分配您刚刚创建的 Floodlightand 活动组的 ID,以及所有其他必填字段。
    # Construct and save floodlight activity.
    floodlight_activity = {
        'countingMethod': 'STANDARD_COUNTING',
        'expectedUrl': 'http://www.google.com',
        'floodlightActivityGroupId': activity_group_id,
        'floodlightTagType': 'GLOBAL_SITE_TAG',
        'name': 'Test Floodlight Activity'
    }
    
  4. 通过调用 floodlightActivities.insert()(该方法会返回新创建的活动的 ID)来保存新创建的活动。
    request = service.floodlightActivities().insert(
        profileId=profile_id, body=floodlight_activity)
    
  5. 通过调用 floodlightActivities.generatetag() 并提供新创建的活动的 floodlightActivityId 来生成代码。然后,将这些代码发送给广告客户的网站站长。
    # Construct the request.
    request = service.floodlightActivities().generatetag(
        profileId=profile_id, floodlightActivityId=activity_id)
    
    # Execute request and print response.
    response = request.execute()
    

Ruby

  1. 创建一个新的 Floodlight 活动组,从而传入 nametypefloodlightConfigurationId 的值。
    # Create a new floodlight activity group resource to insert.
    activity_group =
      DfareportingUtils::API_NAMESPACE::FloodlightActivityGroup.new(
        floodlight_configuration_id: floodlight_config_id,
        name:
          format('Example Floodlight Activity Group #%s', SecureRandom.hex(3)),
        type: 'COUNTER'
      )
    
  2. 通过调用 floodlightActivityGroups.insert()(该方法会返回新活动组的 ID)来保存该 Floodlight 活动组。
    # Insert the floodlight activity group.
    result = service.insert_floodlight_activity_group(profile_id, activity_group)
    
  3. 创建一个新的 Floodlight 活动,并为其分配您刚刚创建的 Floodlightand 活动组的 ID,以及所有其他必填字段。
    # Create a new floodlight activity resource to insert.
    activity = DfareportingUtils::API_NAMESPACE::FloodlightActivity.new(
      counting_method: 'STANDARD_COUNTING',
      expected_url: 'http://www.google.com',
      floodlight_activity_group_id: activity_group_id,
      floodlight_tag_type: 'GLOBAL_SITE_TAG',
      name: format('Example Floodlight Activity #%s', SecureRandom.hex(3))
    )
    
  4. 通过调用 floodlightActivities.insert()(该方法会返回新创建的活动的 ID)来保存新创建的活动。
    # Insert the floodlight activity.
    result = service.insert_floodlight_activity(profile_id, activity)
    
  5. 通过调用 floodlightActivities.generatetag() 并提供新创建的活动的 floodlightActivityId 来生成代码。然后,将这些代码发送给广告客户的网站站长。
    # Construct the request.
    result = service.generatetag_floodlight_activity(profile_id,
      floodlight_activity_id: activity_id)
    

生成展示位置代码

最后一步是生成 HTML 代码并将其发送给发布商,以便展示您的广告。要通过该 API 生成代码,请向 placements.generatetags() 发出请求,并在请求中指定一组 placementIdstagFormats

C#

// Generate the placement activity tags.
PlacementsResource.GeneratetagsRequest request =
    service.Placements.Generatetags(profileId);
request.CampaignId = campaignId;
request.TagFormats =
    PlacementsResource.GeneratetagsRequest.TagFormatsEnum.PLACEMENTTAGIFRAMEJAVASCRIPT;
request.PlacementIds = placementId.ToString();

PlacementsGenerateTagsResponse response = request.Execute();

Java

// Generate the placement activity tags.
Generatetags request = reporting.placements().generatetags(profileId);
request.setCampaignId(campaignId);
request.setTagFormats(tagFormats);
request.setPlacementIds(ImmutableList.of(placementId));

PlacementsGenerateTagsResponse response = request.execute();

PHP

$placementTags = $this->service->placements->generatetags(
    $values['user_profile_id'],
    ['campaignId' => $values['campaign_id'],
     'placementIds' => [$values['placement_id']],
     'tagFormats' => ['PLACEMENT_TAG_STANDARD',
                      'PLACEMENT_TAG_IFRAME_JAVASCRIPT',
                      'PLACEMENT_TAG_INTERNAL_REDIRECT']
    ]
);

Python

# Construct the request.
request = service.placements().generatetags(
    profileId=profile_id, campaignId=campaign_id,
    placementIds=[placement_id])

# Execute request and print response.
response = request.execute()

Ruby

# Construct the request.
result = service.generate_placement_tags(profile_id,
  campaign_id: campaign_id,
  placement_ids: [placement_id])