Remarketing Samples

The code samples below provide examples of common remarketing functions using the AdWords API. Client Library.

Add audience

// Copyright 2017 Google Inc. All Rights Reserved.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

package adwords.axis.v201705.remarketing;

import com.google.api.ads.adwords.axis.factory.AdWordsServices;
import com.google.api.ads.adwords.axis.v201705.cm.AdWordsConversionTracker;
import com.google.api.ads.adwords.axis.v201705.cm.ConversionTracker;
import com.google.api.ads.adwords.axis.v201705.cm.ConversionTrackerPage;
import com.google.api.ads.adwords.axis.v201705.cm.ConversionTrackerServiceInterface;
import com.google.api.ads.adwords.axis.v201705.cm.Operator;
import com.google.api.ads.adwords.axis.v201705.cm.Predicate;
import com.google.api.ads.adwords.axis.v201705.cm.PredicateOperator;
import com.google.api.ads.adwords.axis.v201705.cm.Selector;
import com.google.api.ads.adwords.axis.v201705.rm.AdwordsUserListServiceInterface;
import com.google.api.ads.adwords.axis.v201705.rm.BasicUserList;
import com.google.api.ads.adwords.axis.v201705.rm.UserList;
import com.google.api.ads.adwords.axis.v201705.rm.UserListConversionType;
import com.google.api.ads.adwords.axis.v201705.rm.UserListMembershipStatus;
import com.google.api.ads.adwords.axis.v201705.rm.UserListOperation;
import com.google.api.ads.adwords.axis.v201705.rm.UserListReturnValue;
import com.google.api.ads.adwords.lib.client.AdWordsSession;
import com.google.api.ads.adwords.lib.factory.AdWordsServicesInterface;
import com.google.api.ads.common.lib.auth.OfflineCredentials;
import com.google.api.ads.common.lib.auth.OfflineCredentials.Api;
import com.google.api.client.auth.oauth2.Credential;
import java.util.ArrayList;
import java.util.HashMap;
import java.util.List;
import java.util.Map;

/**
 * This example adds a remarketing user list (a.k.a. audience).
 *
 * <p>Credentials and properties in {@code fromFile()} are pulled from the
 * "ads.properties" file. See README for more info.
 */
public class AddAudience {

  public static void main(String[] args) throws Exception {
    // Generate a refreshable OAuth2 credential.
    Credential oAuth2Credential = new OfflineCredentials.Builder()
        .forApi(Api.ADWORDS)
        .fromFile()
        .build()
        .generateCredential();

    // Construct an AdWordsSession.
    AdWordsSession session = new AdWordsSession.Builder()
        .fromFile()
        .withOAuth2Credential(oAuth2Credential)
        .build();

    AdWordsServicesInterface adWordsServices = AdWordsServices.getInstance();

    runExample(adWordsServices, session);
  }

  public static void runExample(
      AdWordsServicesInterface adWordsServices, AdWordsSession session) throws Exception {
    // Get the UserListService.
    AdwordsUserListServiceInterface userListService =
        adWordsServices.get(session, AdwordsUserListServiceInterface.class);

    // Get the ConversionTrackerService.
    ConversionTrackerServiceInterface conversionTrackerService =
        adWordsServices.get(session, ConversionTrackerServiceInterface.class);

    // Create conversion type (tag).
    UserListConversionType conversionType = new UserListConversionType();
    conversionType.setName("Mars cruise customers #" + System.currentTimeMillis());

    // Create remarketing user list.
    BasicUserList userList = new BasicUserList();
    userList.setName("Mars cruise customers #" + System.currentTimeMillis());
    userList.setDescription("A list of mars cruise customers in the last year");
    userList.setMembershipLifeSpan(365L);
    userList.setConversionTypes(new UserListConversionType[] {conversionType});

    // You can optionally provide these field(s).
    userList.setStatus(UserListMembershipStatus.OPEN);

    // Create operations.
    UserListOperation operation = new UserListOperation();
    operation.setOperand(userList);
    operation.setOperator(Operator.ADD);

    UserListOperation[] operations = new UserListOperation[] {operation};

    // Add user list.
    UserListReturnValue result = userListService.mutate(operations);

    // Display results.
    // Capture the ID(s) of the conversion.
    List<String> conversionIds = new ArrayList<String>();
    for (UserList userListResult : result.getValue()) {
      if (userListResult instanceof BasicUserList) {
        BasicUserList remarketingUserList = (BasicUserList) userListResult;
        for (UserListConversionType userListConversionType : remarketingUserList
            .getConversionTypes()) {
          conversionIds.add(userListConversionType.getId().toString());
        }
      }
    }

    // Create predicate and selector.
    Predicate predicate = new Predicate();
    predicate.setField("Id");
    predicate.setOperator(PredicateOperator.IN);
    predicate.setValues(conversionIds.toArray(new String[0]));
    Selector selector = new Selector();
    selector.setFields(new String[] {"Id"});
    selector.setPredicates(new Predicate[] {predicate});

    // Get all conversion trackers.
    Map<Long, AdWordsConversionTracker> conversionTrackers =
        new HashMap<Long, AdWordsConversionTracker>();
    ConversionTrackerPage page = conversionTrackerService.get(selector);
    if (page != null && page.getEntries() != null) {
      for (ConversionTracker conversionTracker : page.getEntries()) {
        conversionTrackers.put(conversionTracker.getId(),
            (AdWordsConversionTracker) conversionTracker);
      }
    }

    // Display user lists.
    for (UserList userListResult : result.getValue()) {
      System.out.printf("User list with name '%s' and ID %d was added.%n",
          userListResult.getName(), userListResult.getId());

      // Display user list associated conversion code snippets.
      if (userListResult instanceof BasicUserList) {
        BasicUserList remarketingUserList = (BasicUserList) userListResult;
        for (UserListConversionType userListConversionType : remarketingUserList
            .getConversionTypes()) {
          System.out.printf("Conversion type code snippet associated to the list:%n%s%n",
              conversionTrackers.get(userListConversionType.getId()).getSnippet());
        }
      }
    }
  }
}

Add conversion tracker

// Copyright 2017 Google Inc. All Rights Reserved.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

package adwords.axis.v201705.remarketing;

import com.google.api.ads.adwords.axis.factory.AdWordsServices;
import com.google.api.ads.adwords.axis.v201705.cm.AdWordsConversionTracker;
import com.google.api.ads.adwords.axis.v201705.cm.AdWordsConversionTrackerTextFormat;
import com.google.api.ads.adwords.axis.v201705.cm.ConversionTracker;
import com.google.api.ads.adwords.axis.v201705.cm.ConversionTrackerCategory;
import com.google.api.ads.adwords.axis.v201705.cm.ConversionTrackerOperation;
import com.google.api.ads.adwords.axis.v201705.cm.ConversionTrackerReturnValue;
import com.google.api.ads.adwords.axis.v201705.cm.ConversionTrackerServiceInterface;
import com.google.api.ads.adwords.axis.v201705.cm.ConversionTrackerStatus;
import com.google.api.ads.adwords.axis.v201705.cm.Operator;
import com.google.api.ads.adwords.lib.client.AdWordsSession;
import com.google.api.ads.adwords.lib.factory.AdWordsServicesInterface;
import com.google.api.ads.common.lib.auth.OfflineCredentials;
import com.google.api.ads.common.lib.auth.OfflineCredentials.Api;
import com.google.api.client.auth.oauth2.Credential;

/**
 * This example adds an AdWords conversion.
 *
 * <p>Credentials and properties in {@code fromFile()} are pulled from the
 * "ads.properties" file. See README for more info.
 */
public class AddConversionTracker {

  public static void main(String[] args) throws Exception {
    // Generate a refreshable OAuth2 credential.
    Credential oAuth2Credential = new OfflineCredentials.Builder()
        .forApi(Api.ADWORDS)
        .fromFile()
        .build()
        .generateCredential();

    // Construct an AdWordsSession.
    AdWordsSession session = new AdWordsSession.Builder()
        .fromFile()
        .withOAuth2Credential(oAuth2Credential)
        .build();

    AdWordsServicesInterface adWordsServices = AdWordsServices.getInstance();

    runExample(adWordsServices, session);
  }

  public static void runExample(
      AdWordsServicesInterface adWordsServices, AdWordsSession session) throws Exception {
    // Get the ConversionTrackerService.
    ConversionTrackerServiceInterface service =
        adWordsServices.get(session, ConversionTrackerServiceInterface.class);

    // Create AdWords conversion.
    AdWordsConversionTracker adWordsConversionTracker = new AdWordsConversionTracker();
    adWordsConversionTracker.setName("Earth to Mars Cruises Conversion # "
        + System.currentTimeMillis());
    adWordsConversionTracker.setCategory(ConversionTrackerCategory.DEFAULT);
    adWordsConversionTracker.setTextFormat(AdWordsConversionTrackerTextFormat.HIDDEN);

    // You can optionally provide these field(s).
    adWordsConversionTracker.setStatus(ConversionTrackerStatus.ENABLED);
    adWordsConversionTracker.setViewthroughLookbackWindow(15);
    adWordsConversionTracker.setConversionPageLanguage("en");
    adWordsConversionTracker.setBackgroundColor("#0000FF");
    adWordsConversionTracker.setDefaultRevenueValue(1d);
    adWordsConversionTracker.setAlwaysUseDefaultRevenueValue(Boolean.TRUE);

    // Create operations.
    ConversionTrackerOperation operation = new ConversionTrackerOperation();
    operation.setOperator(Operator.ADD);
    operation.setOperand(adWordsConversionTracker);

    ConversionTrackerOperation[] operations = new ConversionTrackerOperation[] {operation};

    // Add conversion.
    ConversionTrackerReturnValue result = service.mutate(operations);

    // Display conversion.
    for (ConversionTracker conversionTracker : result.getValue()) {
      if (conversionTracker instanceof AdWordsConversionTracker) {
        AdWordsConversionTracker newAdWordsConversionTracker =
            (AdWordsConversionTracker) conversionTracker;
        System.out.printf("Conversion with ID %d, name '%s', status '%s', "
            + "category '%s' and snippet '%s' was added.%n",
            newAdWordsConversionTracker.getId(), newAdWordsConversionTracker.getName(),
            newAdWordsConversionTracker.getStatus(), newAdWordsConversionTracker.getCategory(),
            newAdWordsConversionTracker.getSnippet());
      } else {
        System.out.printf("Conversion with ID %d, name '%s', status '%s', "
            + "category '%s' was added.%n", conversionTracker.getId(),
            conversionTracker.getName(), conversionTracker.getStatus(),
            conversionTracker.getCategory());
      }
    }
  }
}

Add CRM-based user list

// Copyright 2017 Google Inc. All Rights Reserved.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

package adwords.axis.v201705.remarketing;

import com.google.api.ads.adwords.axis.factory.AdWordsServices;
import com.google.api.ads.adwords.axis.v201705.cm.Operator;
import com.google.api.ads.adwords.axis.v201705.rm.AdwordsUserListServiceInterface;
import com.google.api.ads.adwords.axis.v201705.rm.CrmBasedUserList;
import com.google.api.ads.adwords.axis.v201705.rm.Member;
import com.google.api.ads.adwords.axis.v201705.rm.MutateMembersOperand;
import com.google.api.ads.adwords.axis.v201705.rm.MutateMembersOperation;
import com.google.api.ads.adwords.axis.v201705.rm.MutateMembersReturnValue;
import com.google.api.ads.adwords.axis.v201705.rm.UserList;
import com.google.api.ads.adwords.axis.v201705.rm.UserListOperation;
import com.google.api.ads.adwords.axis.v201705.rm.UserListReturnValue;
import com.google.api.ads.adwords.lib.client.AdWordsSession;
import com.google.api.ads.adwords.lib.factory.AdWordsServicesInterface;
import com.google.api.ads.common.lib.auth.OfflineCredentials;
import com.google.api.ads.common.lib.auth.OfflineCredentials.Api;
import com.google.api.client.auth.oauth2.Credential;
import com.google.common.collect.ImmutableList;
import java.io.UnsupportedEncodingException;
import java.security.MessageDigest;
import java.security.NoSuchAlgorithmException;
import java.util.ArrayList;
import java.util.List;

/**
 * This example adds a user list (a.k.a. audience) and uploads members to populate the list.
 *
 * <p>
 * <em>Note:</em> It may take up to several hours for the list to be populated with members.
 * Email addresses must be associated with a Google account.
 * For privacy purposes, the user list size will show as zero until the list has at least 1,000
 * members. After that, the size will be rounded to the two most significant digits.
 * </p>
 *
 * <p>
 * <p>Credentials and properties in {@code fromFile()} are pulled from the
 * "ads.properties" file. See README for more info.
 * </p>
 */
public class AddCrmBasedUserList {

  private static final ImmutableList<String> EMAILS =
      ImmutableList.of("client1@example.com", "client2@example.com", " Client3@example.com ");
  private static final MessageDigest digest = getSHA256MessageDigest();

  public static void main(String[] args) throws Exception {
    // Generate a refreshable OAuth2 credential.
    Credential oAuth2Credential = new OfflineCredentials.Builder()
        .forApi(Api.ADWORDS)
        .fromFile()
        .build()
        .generateCredential();

    // Construct an AdWordsSession.
    AdWordsSession session = new AdWordsSession.Builder()
        .fromFile()
        .withOAuth2Credential(oAuth2Credential)
        .build();

    AdWordsServicesInterface adWordsServices = AdWordsServices.getInstance();

    runExample(adWordsServices, session);
  }

  public static void runExample(AdWordsServicesInterface adWordsServices, AdWordsSession session)
      throws Exception {
    // Get the UserListService.
    AdwordsUserListServiceInterface userListService =
        adWordsServices.get(session, AdwordsUserListServiceInterface.class);

    // Create a user list.
    CrmBasedUserList userList = new CrmBasedUserList();
    userList.setName("Customer relationship management list #" + System.currentTimeMillis());
    userList.setDescription("A list of customers that originated from email addresses");

    // See limit here: https://support.google.com/adwords/answer/6276125#requirements.
    userList.setMembershipLifeSpan(30L);

    // Create operation.
    UserListOperation operation = new UserListOperation();
    operation.setOperand(userList);
    operation.setOperator(Operator.ADD);

    // Add user list.
    UserListReturnValue result = userListService.mutate(new UserListOperation[] {operation});

    // Display user list.
    UserList userListAdded = result.getValue(0);
    System.out.printf(
        "User list with name '%s' and ID %d was added.%n",
        userListAdded.getName(), userListAdded.getId());

    // Get user list ID.
    Long userListId = userListAdded.getId();

    // Create operation to add members to the user list based on email addresses.
    MutateMembersOperation mutateMembersOperation = new MutateMembersOperation();
    MutateMembersOperand operand = new MutateMembersOperand();
    operand.setUserListId(userListId);

    // Hash normalized email addresses based on SHA-256 hashing algorithm.
    List<Member> members = new ArrayList<>(EMAILS.size());
    for (String email : EMAILS) {
      String normalizedEmail = toNormalizedString(email);
      Member member = new Member();
      member.setHashedEmail(toSHA256String(normalizedEmail));
      members.add(member);
    }

    // Adding address info is currently available on a whitelist-only basis. This code demonstrates
    // how to do it, and you can uncomment it if you are on the whitelist.
    //  String firstName = "John";
    //  String lastName = "Doe";
    //  String countryCode = "US";
    //  String zipCode = "10011";
    //
    //  com.google.api.ads.adwords.axis.v201705.rm.AddressInfo addressInfo = new AddressInfo();
    //  // First and last name must be normalized and hashed.
    //  addressInfo.setHashedFirstName(toSHA256String(toNormalizedString(firstName)));
    //  addressInfo.setHashedLastName(toSHA256String(toNormalizedString(lastName)));
    //  // Country code and zip code are sent in plaintext.
    //  addressInfo.setCountryCode(countryCode);
    //  addressInfo.setZipCode(zipCode);
    //
    //  Member memberByAddress = new Member();
    //  memberByAddress.setAddressInfo(addressInfo);
    //  members.add(memberByAddress);

    operand.setMembersList(members.toArray(new Member[members.size()]));
    mutateMembersOperation.setOperand(operand);
    mutateMembersOperation.setOperator(Operator.ADD);

    // Add members to the user list based on email addresses.
    MutateMembersReturnValue mutateMembersResult =
        userListService.mutateMembers(new MutateMembersOperation[] {mutateMembersOperation});

    // Display results.
    // Reminder: it may take several hours for the list to be populated with members.
    for (UserList userListResult : mutateMembersResult.getUserLists()) {
      System.out.printf(
          "%d email addresses were uploaded to user list with name '%s' and ID %d "
              + "and are scheduled for review.%n",
          EMAILS.size(), userListResult.getName(), userListResult.getId());
    }
  }

  /**
   * Hash a string using SHA-256 hashing algorithm.
   *
   * @param str the string to hash.
   * @return the SHA-256 hash string representation.
   * @throws UnsupportedEncodingException If UTF-8 charset is not supported.
   */
  private static String toSHA256String(String str) throws UnsupportedEncodingException {
    byte[] hash = digest.digest(str.getBytes("UTF-8"));
    StringBuilder result = new StringBuilder();
    for (byte b : hash) {
      result.append(String.format("%02x", b));
    }

    return result.toString();
  }

  /**
   * Removes leading and trailing whitespace and converts all characters to lower case.
   *
   * @param value the string to normalize.
   * @return a normalized copy of the string.
   */
  private static String toNormalizedString(String value) {
    return value.trim().toLowerCase();
  }

  /** Returns SHA-256 hashing algorithm. */
  private static MessageDigest getSHA256MessageDigest() {
    try {
      return MessageDigest.getInstance("SHA-256");
    } catch (NoSuchAlgorithmException e) {
      throw new RuntimeException("Missing SHA-256 algorithm implementation.", e);
    }
  }
}

Add rule-based user list

// Copyright 2017 Google Inc. All Rights Reserved.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

package adwords.axis.v201705.remarketing;

import com.google.api.ads.adwords.axis.factory.AdWordsServices;
import com.google.api.ads.adwords.axis.v201705.cm.Operator;
import com.google.api.ads.adwords.axis.v201705.rm.AdwordsUserListServiceInterface;
import com.google.api.ads.adwords.axis.v201705.rm.DateKey;
import com.google.api.ads.adwords.axis.v201705.rm.DateRuleItem;
import com.google.api.ads.adwords.axis.v201705.rm.DateRuleItemDateOperator;
import com.google.api.ads.adwords.axis.v201705.rm.DateSpecificRuleUserList;
import com.google.api.ads.adwords.axis.v201705.rm.ExpressionRuleUserList;
import com.google.api.ads.adwords.axis.v201705.rm.NumberKey;
import com.google.api.ads.adwords.axis.v201705.rm.NumberRuleItem;
import com.google.api.ads.adwords.axis.v201705.rm.NumberRuleItemNumberOperator;
import com.google.api.ads.adwords.axis.v201705.rm.Rule;
import com.google.api.ads.adwords.axis.v201705.rm.RuleBasedUserListPrepopulationStatus;
import com.google.api.ads.adwords.axis.v201705.rm.RuleItem;
import com.google.api.ads.adwords.axis.v201705.rm.RuleItemGroup;
import com.google.api.ads.adwords.axis.v201705.rm.StringKey;
import com.google.api.ads.adwords.axis.v201705.rm.StringRuleItem;
import com.google.api.ads.adwords.axis.v201705.rm.StringRuleItemStringOperator;
import com.google.api.ads.adwords.axis.v201705.rm.UserList;
import com.google.api.ads.adwords.axis.v201705.rm.UserListOperation;
import com.google.api.ads.adwords.axis.v201705.rm.UserListReturnValue;
import com.google.api.ads.adwords.axis.v201705.rm.UserListRuleTypeEnumsEnum;
import com.google.api.ads.adwords.lib.client.AdWordsSession;
import com.google.api.ads.adwords.lib.factory.AdWordsServicesInterface;
import com.google.api.ads.common.lib.auth.OfflineCredentials;
import com.google.api.ads.common.lib.auth.OfflineCredentials.Api;
import com.google.api.client.auth.oauth2.Credential;
import java.util.ArrayList;
import java.util.List;
import org.joda.time.DateTime;

/**
 * This example adds two rule-based remarketing user lists: one with no site visit date
 * restrictions, and another that will only include users who visit your site in the
 * next six months.
 *
 * <p>Credentials and properties in {@code fromFile()} are pulled from the
 * "ads.properties" file. See README for more info.
 */
public class AddRuleBasedUserLists {

  private static final String DATE_FORMAT_STRING = "yyyyMMdd";
  
  public static void main(String[] args) throws Exception {
    // Generate a refreshable OAuth2 credential.
    Credential oAuth2Credential = new OfflineCredentials.Builder()
        .forApi(Api.ADWORDS)
        .fromFile()
        .build()
        .generateCredential();

    // Construct an AdWordsSession.
    AdWordsSession session = new AdWordsSession.Builder()
        .fromFile()
        .withOAuth2Credential(oAuth2Credential)
        .build();

    AdWordsServicesInterface adWordsServices = AdWordsServices.getInstance();

    runExample(adWordsServices, session);
  }

  public static void runExample(AdWordsServicesInterface adWordsServices, AdWordsSession session)
      throws Exception {
    
    // Get the AdwordsUserListService.
    AdwordsUserListServiceInterface userListService =
        adWordsServices.get(session, AdwordsUserListServiceInterface.class);
   
    // First rule item group - users who visited the checkout page and had more than one item
    // in their shopping cart.
    StringKey pageTypeKey = new StringKey("ecomm_pagetype");
    
    StringRuleItem checkoutStringRuleItem = new StringRuleItem();
    checkoutStringRuleItem.setKey(pageTypeKey);
    checkoutStringRuleItem.setOp(StringRuleItemStringOperator.EQUALS);
    checkoutStringRuleItem.setValue("checkout");
    
    RuleItem checkoutRuleItem = new RuleItem();
    checkoutRuleItem.setStringRuleItem(checkoutStringRuleItem);

    NumberKey cartSizeKey = new NumberKey("cartsize");
    
    NumberRuleItem cartSizeNumberRuleItem = new NumberRuleItem();
    cartSizeNumberRuleItem.setKey(cartSizeKey);
    cartSizeNumberRuleItem.setOp(NumberRuleItemNumberOperator.GREATER_THAN);
    cartSizeNumberRuleItem.setValue(1.0);

    RuleItem cartSizeRuleItem = new RuleItem();
    cartSizeRuleItem.setNumberRuleItem(cartSizeNumberRuleItem);

    // Combine the two rule items into a RuleItemGroup so AdWords will AND their rules
    // together.
    RuleItemGroup checkoutMultipleItemGroup = new RuleItemGroup();
    checkoutMultipleItemGroup.setItems(new RuleItem[] {checkoutRuleItem, cartSizeRuleItem});

    // Second rule item group - users who checked out within the next 3 months.
    DateKey checkoutDateKey = new DateKey("checkoutdate");
    
    DateRuleItem startDateDateRuleItem = new DateRuleItem();
    startDateDateRuleItem.setKey(checkoutDateKey);
    startDateDateRuleItem.setOp(DateRuleItemDateOperator.AFTER);
    startDateDateRuleItem.setValue(new DateTime().toString(DATE_FORMAT_STRING));
    
    RuleItem startDateRuleItem = new RuleItem();
    startDateRuleItem.setDateRuleItem(startDateDateRuleItem);

    DateRuleItem endDateDateRuleItem = new DateRuleItem();
    endDateDateRuleItem.setKey(checkoutDateKey);
    endDateDateRuleItem.setOp(DateRuleItemDateOperator.BEFORE);
    endDateDateRuleItem.setValue(new DateTime().plusMonths(3).toString(DATE_FORMAT_STRING));
    
    RuleItem endDateRuleItem = new RuleItem();
    endDateRuleItem.setDateRuleItem(endDateDateRuleItem);

    // Combine the date rule items into a RuleItemGroup.
    RuleItemGroup checkedOutNextThreeMonthsItemGroup = new RuleItemGroup();
    checkedOutNextThreeMonthsItemGroup.setItems(
        new RuleItem[] {startDateRuleItem, endDateRuleItem});

    // Combine the rule item groups into a Rule so AdWords knows how to apply the rules.
    Rule rule = new Rule();
    rule.setGroups(
        new RuleItemGroup[] {checkoutMultipleItemGroup, checkedOutNextThreeMonthsItemGroup});
    // ExpressionRuleUserLists can use either CNF or DNF for matching. CNF means 'at least one item
    // in each rule item group must match', and DNF means 'at least one entire rule item group must
    // match'. DateSpecificRuleUserList only supports DNF. You can also omit the rule type
    // altogether to default to DNF.
    rule.setRuleType(UserListRuleTypeEnumsEnum.DNF);
    
    // Create the user list with no restrictions on site visit date.
    ExpressionRuleUserList expressionUserList = new ExpressionRuleUserList();
    expressionUserList.setName(
        "Expression based user list created at " + new DateTime().toString("yyyyMMdd_HHmmss"));
    expressionUserList.setDescription(
        "Users who checked out in three month window OR visited the checkout page "
        + "with more than one item in their cart");
    expressionUserList.setRule(rule);

    // Optional: Set the prepopulationStatus to REQUESTED to include past users in the user list.
    expressionUserList.setPrepopulationStatus(RuleBasedUserListPrepopulationStatus.REQUESTED);
    
    // Create the user list restricted to users who visit your site within the next six months.
    DateTime startDate = new DateTime();
    DateTime endDate = startDate.plusMonths(6);

    DateSpecificRuleUserList dateUserList = new DateSpecificRuleUserList();
    dateUserList.setName(
        "Date rule user list created at " + new DateTime().toString("yyyyMMdd_HHmmss"));
    dateUserList.setDescription(String.format("Users who visited the site between %s and %s and "
        + "checked out in three month window OR visited the checkout page "
        + "with more than one item in their cart", startDate.toString(DATE_FORMAT_STRING),
        endDate.toString(DATE_FORMAT_STRING)));
    dateUserList.setRule(rule);

    // Set the start and end dates of the user list.
    dateUserList.setStartDate(startDate.toString(DATE_FORMAT_STRING));
    dateUserList.setEndDate(endDate.toString(DATE_FORMAT_STRING));

    // Create operations to add the user lists.
    List<UserListOperation> operations = new ArrayList<>();
    for (UserList userList : new UserList[] {expressionUserList, dateUserList}) {
      UserListOperation operation = new UserListOperation();
      operation.setOperand(userList);
      operation.setOperator(Operator.ADD);
      operations.add(operation);
    }

    // Submit the operations.
    UserListReturnValue result =
        userListService.mutate(operations.toArray(new UserListOperation[operations.size()]));

    // Display the results.
    for (UserList userListResult : result.getValue()) {
      System.out.printf("User list added with ID %d, name '%s', status '%s', list type '%s',"
          + " accountUserListStatus '%s', description '%s'.%n",
          userListResult.getId(),
          userListResult.getName(),
          userListResult.getStatus().getValue(),
          userListResult.getListType() == null ? null : userListResult.getListType().getValue(),
          userListResult.getAccountUserListStatus().getValue(),
          userListResult.getDescription());
    }
  }
}

Upload offline conversions

// Copyright 2017 Google Inc. All Rights Reserved.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

package adwords.axis.v201705.remarketing;

import com.google.api.ads.adwords.axis.factory.AdWordsServices;
import com.google.api.ads.adwords.axis.v201705.cm.OfflineConversionFeed;
import com.google.api.ads.adwords.axis.v201705.cm.OfflineConversionFeedOperation;
import com.google.api.ads.adwords.axis.v201705.cm.OfflineConversionFeedReturnValue;
import com.google.api.ads.adwords.axis.v201705.cm.OfflineConversionFeedServiceInterface;
import com.google.api.ads.adwords.axis.v201705.cm.Operator;
import com.google.api.ads.adwords.lib.client.AdWordsSession;
import com.google.api.ads.adwords.lib.factory.AdWordsServicesInterface;
import com.google.api.ads.common.lib.auth.OfflineCredentials;
import com.google.api.ads.common.lib.auth.OfflineCredentials.Api;
import com.google.api.client.auth.oauth2.Credential;

/**
 * This code example imports offline conversion values for specific clicks to
 * your account. To get Google Click ID for a click, run
 * CLICK_PERFORMANCE_REPORT. To set up a conversion tracker, run the
 * AddConversionTracker.java example.
 */
public class UploadOfflineConversions {

  public static void main(String[] args) throws Exception {
    // Generate a refreshable OAuth2 credential.
    Credential oAuth2Credential = new OfflineCredentials.Builder()
        .forApi(Api.ADWORDS)
        .fromFile()
        .build()
        .generateCredential();

    // Construct an AdWordsSession.
    AdWordsSession session = new AdWordsSession.Builder()
        .fromFile()
        .withOAuth2Credential(oAuth2Credential)
        .build();

    AdWordsServicesInterface adWordsServices = AdWordsServices.getInstance();

    // Name of the conversion tracker to upload to.
    String conversionName = "INSERT_CONVERSION_NAME_HERE";
    
    // Google Click ID should be newer than 30 days.
    String gClId = "INSERT_GOOGLE_CLICK_ID_HERE";
    
    // Conversion time should be after the click time.
    String conversionTime = "INSERT_CONVERSION_TIME_HERE";
    Double conversionValue = Double.valueOf("INSERT_CONVERSION_VALUE_HERE");

    runExample(adWordsServices, session, conversionName, gClId, conversionTime, conversionValue);
  }

  public static void runExample(AdWordsServicesInterface adWordsServices, AdWordsSession session, 
      String conversionName, String gClid, String conversionTime, 
      double conversionValue) throws Exception {

    // Get the OfflineConversionFeedService.
    OfflineConversionFeedServiceInterface offlineConversionFeedService =
        adWordsServices.get(session, OfflineConversionFeedServiceInterface.class);

    // Associate offline conversions with the existing named conversion tracker. If this tracker
    // was newly created, it may be a few hours before it can accept conversions.
    OfflineConversionFeed feed = new OfflineConversionFeed();
    feed.setConversionName(conversionName);
    feed.setConversionTime(conversionTime);
    feed.setConversionValue(conversionValue);
    feed.setGoogleClickId(gClid);

    OfflineConversionFeedOperation offlineConversionOperation =
        new OfflineConversionFeedOperation();
    offlineConversionOperation.setOperator(Operator.ADD);
    offlineConversionOperation.setOperand(feed);

    OfflineConversionFeedReturnValue offlineConversionReturnValue = offlineConversionFeedService
        .mutate(new OfflineConversionFeedOperation[] {offlineConversionOperation});

    OfflineConversionFeed newFeed = offlineConversionReturnValue.getValue(0);

    System.out.printf(
        "Uploaded offline conversion value of %.4f for Google Click ID '%s' to '%s'.%n",
        newFeed.getConversionValue(), newFeed.getGoogleClickId(), newFeed.getConversionName());
  }
}

Upload offline call conversions

// Copyright 2017 Google Inc. All Rights Reserved.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
// http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

package adwords.axis.v201705.remarketing;

import com.google.api.ads.adwords.axis.factory.AdWordsServices;
import com.google.api.ads.adwords.axis.v201705.cm.OfflineCallConversionFeed;
import com.google.api.ads.adwords.axis.v201705.cm.OfflineCallConversionFeedOperation;
import com.google.api.ads.adwords.axis.v201705.cm.OfflineCallConversionFeedReturnValue;
import com.google.api.ads.adwords.axis.v201705.cm.OfflineCallConversionFeedServiceInterface;
import com.google.api.ads.adwords.axis.v201705.cm.Operator;
import com.google.api.ads.adwords.lib.client.AdWordsSession;
import com.google.api.ads.adwords.lib.factory.AdWordsServicesInterface;
import com.google.api.ads.common.lib.auth.OfflineCredentials;
import com.google.api.ads.common.lib.auth.OfflineCredentials.Api;
import com.google.api.client.auth.oauth2.Credential;

/**
 * This example imports offline call conversion values for calls related to the ads in your account.
 *
 * <p>Credentials and properties in {@code fromFile()} are pulled from the "ads.properties" file.
 * See README for more info.
 */
public class UploadOfflineCallConversions {

  public static void main(String[] args) throws Exception {
    // Generate a refreshable OAuth2 credential.
    Credential oAuth2Credential =
        new OfflineCredentials.Builder()
            .forApi(Api.ADWORDS)
            .fromFile()
            .build()
            .generateCredential();

    // Construct an AdWordsSession.
    AdWordsSession session =
        new AdWordsSession.Builder().fromFile().withOAuth2Credential(oAuth2Credential).build();

    AdWordsServicesInterface adWordsServices = AdWordsServices.getInstance();

    // Replace with valid values of your account.
    String callerId = "INSERT_CALLER_ID_HERE";

    // For times, use the format yyyyMMdd HHmmss tz. For more details on formats, see:
    // https://developers.google.com/adwords/api/docs/appendix/codes-formats#date-and-time-formats
    // For time zones, see:
    // https://developers.google.com/adwords/api/docs/appendix/codes-formats#timezone-ids
    String callStartTime = "INSERT_CALL_START_TIME_HERE";

    // Name of the conversion tracker to upload to.
    String conversionName = "INSERT_CONVERSION_NAME_HERE";

    String conversionTime = "INSERT_CONVERSION_TIME_HERE";
    Double conversionValue = Double.valueOf("INSERT_CONVERSION_VALUE_HERE");

    runExample(
        adWordsServices,
        session,
        callerId,
        callStartTime,
        conversionName,
        conversionTime,
        conversionValue);
  }

  public static void runExample(
      AdWordsServicesInterface adWordsServices,
      AdWordsSession session,
      String callerId,
      String callStartTime,
      String conversionName,
      String conversionTime,
      double conversionValue)
      throws Exception {

    // Get the OfflineCallConversionFeedService.
    OfflineCallConversionFeedServiceInterface offlineCallConversionFeedService =
        adWordsServices.get(session, OfflineCallConversionFeedServiceInterface.class);

    // Associate offline call conversions with the existing named conversion tracker. If this
    // tracker was newly created, it may be a few hours before it can accept conversions.
    OfflineCallConversionFeed feed = new OfflineCallConversionFeed();
    feed.setCallerId(callerId);
    feed.setCallStartTime(callStartTime);
    feed.setConversionName(conversionName);
    feed.setConversionTime(conversionTime);
    feed.setConversionValue(conversionValue);

    OfflineCallConversionFeedOperation offlineCallConversionOperation =
        new OfflineCallConversionFeedOperation();
    offlineCallConversionOperation.setOperator(Operator.ADD);
    offlineCallConversionOperation.setOperand(feed);

    // This example uploads only one call conversion, but you can upload multiple call conversions
    // by passing additional operations.
    OfflineCallConversionFeedReturnValue offlineCallConversionReturnValue =
        offlineCallConversionFeedService.mutate(
            new OfflineCallConversionFeedOperation[] {offlineCallConversionOperation});

    // Display results.
    for (OfflineCallConversionFeed feedResult : offlineCallConversionReturnValue.getValue()) {
      System.out.printf(
          "Uploaded offline conversion value of %.4f for caller ID '%s'.%n",
          feedResult.getConversionValue(), feedResult.getCallerId());
    }
  }
}

Send feedback about...

AdWords API
AdWords API
Need help? Visit our support page.