Create a user list

  • expression_rule_user_list defaults to "disjunctive normal form" (OR_OF_ANDS), where every rule item in at least one group must match.

  • "conjunctive normal form" (AND_OF_ORS) is available for expression_rule_user_list using the rule_type field, requiring at least one rule item in each group to match.

  • Attempting to use AND_OF_ORS with date_specific_rule_user_list will cause an error.

  • Past users can be included in a rule-based user list by setting prepopulation_status to REQUESTED, which includes users from the last 30 days depending on list settings and tag date.

  • The prepopulation status can be monitored and will change to FINISHED or FAILED.

You can use user lists in your remarketing campaigns to re-engage with users who have performed specific actions on your website or app. The Google Ads API supports several types of user lists. This guide focuses on creating rule-based user lists using the rule item groups defined in Create rule item groups.

Rule-based user lists

Rule-based user lists built with flexible_rule_user_list can contain multiple rules (inclusive_rule and exclusive_rule, joined by inclusive_rule_operator). Each rule is represented by a UserListRuleInfo message, which has a rule_type field that dictates how rule items within rule item groups are combined.

Although UserListRuleTypeEnum defines both OR_OF_ANDS (disjunctive normal form) and AND_OF_ORS (conjunctive normal form), OR_OF_ANDS is the only supported rule_type for FlexibleRuleUserListInfo (setting AND_OF_ORS returns UserListError.RULE_TYPE_IS_NOT_SUPPORTED). With OR_OF_ANDS, Google Ads ANDs together all rule items in a rule item group, which means that for a given rule, every rule item in at least one rule item group must match for the rule to be satisfied.

After defining the two UserListRuleItemGroupInfo objects in Create rule item groups, combine them into a new user list. The following code example leaves the default OR_OF_ANDS rule type in place, adds both rule item groups to a FlexibleRuleOperandInfo on FlexibleRuleUserListInfo, and mutates the user list:

Java

FlexibleRuleUserListInfo flexibleRuleUserListInfo =
    FlexibleRuleUserListInfo.newBuilder()
        .setInclusiveRuleOperator(UserListFlexibleRuleOperator.AND)
        .addInclusiveOperands(
            FlexibleRuleOperandInfo.newBuilder()
                .setRule(
                    // The default rule_type for a UserListRuleInfo object is OR of ANDs
                    // (disjunctive normal form). That is, rule items will be ANDed together
                    // within rule item groups and the groups themselves will be ORed together.
                    UserListRuleInfo.newBuilder()
                        .addRuleItemGroups(checkoutDateRuleGroup)
                        .addRuleItemGroups(checkoutAndCartSizeRuleGroup))
                // Optional: includes a lookback window for this rule, in days.
                .setLookbackWindowDays(7L))
        .build();

C#

FlexibleRuleUserListInfo flexibleRuleUserListInfo = new FlexibleRuleUserListInfo();
FlexibleRuleOperandInfo flexibleRuleOperandInfo = new FlexibleRuleOperandInfo() {
    Rule = new UserListRuleInfo()
};
flexibleRuleOperandInfo.Rule.RuleItemGroups.Add(checkoutAndCartSizeRuleGroup);
flexibleRuleOperandInfo.Rule.RuleItemGroups.Add(checkoutDateRuleGroup);
flexibleRuleUserListInfo.InclusiveOperands.Add(flexibleRuleOperandInfo);

PHP

$flexibleRuleUserListInfo = new FlexibleRuleUserListInfo(
    [
    'inclusive_rule_operator' => UserListFlexibleRuleOperator::PBAND,
    'inclusive_operands' => [
        new FlexibleRuleOperandInfo(
            [
            'rule' => new UserListRuleInfo(
                [
                // The default rule_type for a UserListRuleInfo object is OR of ANDs
                // (disjunctive normal form). That is, rule items will be ANDed together
                // within rule item groups and the groups themselves will be ORed together.
                'rule_item_groups' => [
                    $checkoutAndCartSizeRuleGroup,
                    $checkoutDateRuleGroup
                ]
                ]
            ),
            // Optionally add a lookback window for this rule, in days.
            'lookback_window_days' => 7
            ]
        )
    ],
    'exclusive_operands' => []
    ]
);

Python

# Create a FlexibleRuleUserListInfo object, or a flexible rule
# representation of visitors with one or multiple actions.
# FlexibleRuleUserListInfo wraps UserListRuleInfo in a
# FlexibleRuleOperandInfo object that represents which user lists to
# include or exclude.
flexible_rule_user_list_info: FlexibleRuleUserListInfo = (
    rule_based_user_list_info.flexible_rule_user_list
)
flexible_rule_user_list_info.inclusive_rule_operator = (
    client.enums.UserListFlexibleRuleOperatorEnum.AND
)
# The default rule_type for a UserListRuleInfo object is OR of
# ANDs (disjunctive normal form). That is, rule items will be
# ANDed together within rule item groups and the groups
# themselves will be ORed together.
rule_operand: FlexibleRuleOperandInfo = client.get_type(
    "FlexibleRuleOperandInfo"
)
rule_operand.rule.rule_item_groups.extend(
    [
        checkout_and_cart_size_rule_group,
        checkout_date_rule_group,
    ]
)
rule_operand.lookback_window_days = 7
flexible_rule_user_list_info.inclusive_operands.append(rule_operand)

Ruby

r.flexible_rule_user_list = client.resource.flexible_rule_user_list_info do |frul|
  frul.inclusive_rule_operator = :AND
  frul.inclusive_operands << client.resource.flexible_rule_operand_info do |froi|
    froi.rule = client.resource.user_list_rule_info do |info|
      info.rule_item_groups += [checkout_date_rule_group, checkout_and_cart_size_rule_group]
    end
    # Optionally include a lookback window for this rule, in days.
    froi.lookback_window_days = 7
  end
end

Perl

my $flexible_rule_user_list_info =
  Google::Ads::GoogleAds::V25::Common::FlexibleRuleUserListInfo->new({
    inclusiveRuleOperator => AND,
    inclusiveOperands     => [
      Google::Ads::GoogleAds::V25::Common::FlexibleRuleOperandInfo->new({
          rule => Google::Ads::GoogleAds::V25::Common::UserListRuleInfo->new({
              # The default rule_type for a UserListRuleInfo object is OR of
              # ANDs (disjunctive normal form). That is, rule items will be
              # ANDed together within rule item groups and the groups
              # themselves will be ORed together.
              ruleItemGroups => [
                $checkout_date_rule_group, $checkout_and_cart_size_rule_group
              ]}
          ),
          # Optionally include a lookback window for this rule, in days.
          lookback_window_days => 7
        })
    ],
    exclusiveOperands => []});

curl

Include past users in a rule-based list

You can also include past website visitors or app users in a rule-based user list (supported on the Display Network only) by setting the prepopulation_status of the user list to REQUESTED, and monitor the progress of the asynchronous prepopulation process by periodically checking the status of this field.

Prepopulation only adds past users from within the last 30 days, depending on the list's membership_life_span (from 1 to 540 days) and the date when the remarketing tag was added. The status updates to FINISHED once the request is processed, or FAILED if the request fails.

Target the user list and adjust bids

Once you have created your UserList, attach its resource name to an AdGroupCriterion or CampaignCriterion and set bid_modifier (for example, 1.25 for a 25% bid increase). For code examples demonstrating how to target a user list and modify bids, see Target the list.

Previous
Creating the rule item groups