Create a Smart campaign and a Smart campaign setting

Smart campaigns depend on a new resource called SmartCampaignSetting, which contains additional configuration options that are not available on the main Campaign resource.

A Smart campaign setting cannot exist without being tied to a campaign, which is part of the reason why it's best to create the two objects in the same mutate request.

Create a campaign

Because a Smart campaign is primarily managed automatically by Google's advertising technology it's not necessary to set many fields on it.

Key requirements for Smart campaigns:

Notice that we set the value for this campaign's resource name using a temporary resource name. This allows the campaign to be referenced by other objects in the mutate request before it exists in the backend.

Python

def _create_smart_campaign_operation(client, customer_id):
    """Creates a MutateOperation that creates a new Smart campaign.

    A temporary ID will be assigned to this campaign so that it can
    be referenced by other objects being created in the same Mutate request.

    Args:
        client: an initialized GoogleAdsClient instance.
        customer_id: a client customer ID.

    Returns:
        a MutateOperation that creates a campaign.
    """
    mutate_operation = client.get_type("MutateOperation")
    campaign = mutate_operation.campaign_operation.create
    campaign.name = f"Smart campaign #{uuid4()}"
    # Set the campaign status as PAUSED. The campaign is the only entity in
    # the mutate request that should have its' status set.
    campaign.status = client.get_type(
        "CampaignStatusEnum"
    ).CampaignStatus.PAUSED
    # Campaign.AdvertisingChannelType is required to be SMART.
    campaign.advertising_channel_type = client.get_type(
        "AdvertisingChannelTypeEnum"
    ).AdvertisingChannelType.SMART
    # Campaign.AdvertisingChannelSubType is required to be SMART_CAMPAIGN.
    campaign.advertising_channel_sub_type = client.get_type(
        "AdvertisingChannelSubTypeEnum"
    ).AdvertisingChannelSubType.SMART_CAMPAIGN
    # Assign the resource name with a temporary ID.
    campaign_service = client.get_service("CampaignService")
    campaign.resource_name = campaign_service.campaign_path(
        customer_id, _SMART_CAMPAIGN_TEMPORARY_ID
    )
    # Set the budget using the given budget resource name.
    campaign.campaign_budget = campaign_service.campaign_budget_path(
        customer_id, _BUDGET_TEMPORARY_ID
    )

    return mutate_operation

Ruby

# Creates a mutate_operation that creates a new Smart campaign.
# A temporary ID will be assigned to this campaign so that it can
# be referenced by other objects being created in the same mutate request.
def create_smart_campaign_operation(
    client,
    customer_id)
  mutate_operation = client.operation.mutate do |m|
    m.campaign_operation = client.operation.create_resource.campaign do |c|
      c.name = "Smart campaign ##{(Time.new.to_f * 1000).to_i}"
      # Sets the campaign status as PAUSED. The campaign is the only entity in
      # the mutate request that should have its' status set.
      c.status = :PAUSED
      # campaign.advertising_channel_type is required to be SMART.
      c.advertising_channel_type = :SMART
      # campaign.advertising_channel_sub_type is required to be SMART_CAMPAIGN.
      c.advertising_channel_sub_type = :SMART_CAMPAIGN
      # Assigns the resource name with a temporary ID.
      c.resource_name = client.path.campaign(customer_id, SMART_CAMPAIGN_TEMPORARY_ID)
      c.campaign_budget = client.path.campaign_budget(customer_id, BUDGET_TEMPORARY_ID)
    end
  end

  mutate_operation
end

Create a Smart campaign setting

The SmartCampaignSetting resource is only used for configuring Smart campaigns and it cannot be created unless a Smart campaign already exists that it can reference. Smart campaign settings are particularly unique for this reason; you can think of them as an extension of the main Campaign resource.

Key requirements for Smart campaign settings:

  • There must be an existing Campaign that it can reference.
  • The relationship to its Campaign is defined in its resource_name not a campaign field.
  • Either the business_location_id or business_name fields must be set.
  • An update_mask must be added onto the update operation, even when using it to create a new Smart campaign setting.

Python

def _create_smart_campaign_setting_operation(
    client, customer_id, business_location_id, business_name
):
    """Creates a MutateOperation to create a new SmartCampaignSetting.

    SmartCampaignSettings are unique in that they only support UPDATE
    operations, which are used to update and create them. Below we will
    use a temporary ID in the resource name to associate it with the
    campaign created in the previous step.

    Args:
        client: an initialized GoogleAdsClient instance.
        customer_id: a client customer ID.
        business_location_id: the ID of a Google My Business location.
        business_name: the name of a Google My Business.

    Returns:
        a MutateOperation that creates a SmartCampaignSetting.
    """
    mutate_operation = client.get_type("MutateOperation")
    smart_campaign_setting = (
        mutate_operation.smart_campaign_setting_operation.update
    )
    # Set a temporary ID in the campaign setting's resource name to associate it
    # with the campaign created in the previous step.
    smart_campaign_setting.resource_name = client.get_service(
        "SmartCampaignSettingService"
    ).smart_campaign_setting_path(customer_id, _SMART_CAMPAIGN_TEMPORARY_ID)

    # Below we configure the SmartCampaignSetting using many of the same
    # details used to generate a budget suggestion.
    smart_campaign_setting.phone_number.country_code = _COUNTRY_CODE
    smart_campaign_setting.phone_number.phone_number = _PHONE_NUMBER
    smart_campaign_setting.final_url = _LANDING_PAGE_URL
    smart_campaign_setting.advertising_language_code = _LANGUAGE_CODE

    # It's required that either a business location ID or a business name is
    # added to the SmartCampaignSetting.
    if business_location_id:
        smart_campaign_setting.business_location_id = business_location_id
    else:
        smart_campaign_setting.business_name = business_name

    # Set the update mask on the operation. This is required since the smart
    # campaign setting is created in an UPDATE operation. Here the update
    # mask will be a list of all the fields that were set on the
    # SmartCampaignSetting.
    client.copy_from(
        mutate_operation.smart_campaign_setting_operation.update_mask,
        protobuf_helpers.field_mask(None, smart_campaign_setting._pb),
    )

    return mutate_operation

Ruby

# Creates a mutate_operation to create a new smart_campaign_setting.
# smart_campaign_settings are unique in that they only support UPDATE
# operations, which are used to update and create them. Below we will
# use a temporary ID in the resource name to associate it with the
# campaign created in the previous step.
def create_smart_campaign_setting_operation(
  client,
  customer_id,
  business_location_id,
  business_name)
  mutate_operation = client.operation.mutate do |m|
    m.smart_campaign_setting_operation =
      client.operation.update_resource.smart_campaign_setting(
        # Sets a temporary ID in the campaign setting's resource name to
        # associate it with the campaign created in the previous step.
        client.path.smart_campaign_setting(
          customer_id, SMART_CAMPAIGN_TEMPORARY_ID)
      ) do |scs|
      # Below we configure the smart_campaign_setting using many of the same
      # details used to generate a budget suggestion.
      scs.phone_number = client.resource.phone_number do |p|
        p.country_code = COUNTRY_CODE
        p.phone_number = PHONE_NUMBER
      end
      scs.final_url = LANDING_PAGE_URL
      scs.advertising_language_code = LANGUAGE_CODE
      # It's required that either a business location ID or a business name is
      # added to the smart_campaign_setting.
      if business_location_id
        scs.business_location_id = business_location_id.to_i
      else
        scs.business_name = business_name
      end
    end
  end

  mutate_operation
end