Before you begin

Create a Google Cloud project

  1. On the Manage resources page in the Google Cloud console, select or create a Google Cloud project.

    Go to the Manage Resources page

  2. Make sure that billing is enabled for your Cloud project. Learn how to check if billing is enabled on a project.

Set up Vertex AI Search for retail

To use Vertex AI Search for retail, along with recommendations, you must turn on Vertex AI Search for retail and accept the Vertex AI Search for Industry terms for data use. If you are also using search, you must enable it. Using search incurs additional costs based on the number of queries. For more information, see Search charges.

To set up Vertex AI Search for retail, complete the following steps:

  1. Go to the Vertex AI Search for retail page in the Google Cloud console.

    Go to the Search for Retail page

  2. On the Set up Vertex AI Search for retail page, click Turn on API.

  3. When Vertex AI Search for retail and Recommendations AI display as On, click Continue.

  4. Read the Vertex AI Search for Industry terms for data use and click Accept if you agree to the data use terms.

    When you accept the data use terms, the Google Cloud console indicates that Vertex AI Search for retail data use terms are accepted.

  5. If you want to use the project with recommendations only, click Get Started.

  6. If you want to turn on search in addition to recommendations, do the following:

    1. Click Continue and then click Turn on on the Turn on search (Optional) page.
    2. Click Get Started.

The Google Cloud console displays the Vertex AI Search for retail components that you have turned on. You can now configure your project's initial settings.

Set up for an existing project

If you set up Vertex AI Search for retail on a Google Cloud project before the data use terms went into effect on April 4, 2022, you must accept the Vertex AI Search for Industry terms to continue using Vertex AI Search for retail with that project. You must also enable search for that project, if required.

To accept the Vertex AI Search for Industry terms for an existing project, complete the following steps:

  1. Go to the Search for Retail page in the Google Cloud console for your project.

    Go to the Search for Retail page

  2. On the Data use terms page, read the Discovery Solutions data use terms and click Accept if you agree to the terms.

  3. If you want to use the project with recommendations only, click Get Started.

  4. If you want to turn on search in addition to recommendations, do the following:

    1. Click Continue and then click Turn on on the Turn on search (Optional) page.
    2. Click Get Started.

Turn off search or Vertex AI Search for retail

Turn off search

If you no longer want to use search, you can turn it off by submitting a support ticket.

To set your ticket to the correct component, select the following fields:

  • Category: Machine Learning
  • Component: Vertex AI Search for retail: search & browse
  • Subcomponent: Account Administration & Billing

For more information on creating a support ticket, see Getting support.

Turn off Vertex AI Search for retail

You can turn off Vertex AI Search for retail at any time by disabling it. This turns off both recommendations and search.

To turn off Vertex AI Search for retail, complete the following steps:

  1. Go to the Vertex AI Search for Retail API/Service Details page in the Google Cloud console.

    Go to Vertex AI Search for retail API Service Details page

  2. Click Disable API.

  3. In the Disable Vertex AI Search for retail API? box, click Disable.

Get started with Vertex AI Search for retail

When you set up Vertex AI Search for retail for a new project, the Google Cloud console displays the following three panels to help you configure your Vertex AI Search for retail project:

  • Data > Catalog: displays your product catalog and a link to import your catalog.

  • Data > Events: displays your user events and a link to import historical user events.

  • Serving configs: contains details on your serving config and a link to create a new serving config.

You can use these panels to import your data and to create an initial configuration for your Vertex AI Search for retail project.

Import your product catalog

To import your product catalog, complete the set of steps for your data source. For more information on product catalogs, see Importing catalog information.

Merchant Center Sync

  1. Click Import product catalog to open the Import Data panel.
  2. Choose Product catalog.
  3. Select Merchant Center Sync as your data source.
  4. Select your Merchant Center account. Check User Access if you don't see your account.
  5. Optional: Select Merchant Center feeds filter to import only offers from selected feeds.

    If not specified, offers from all feeds are imported (including future feeds).
  6. Optional: To import only offers targeted to certain countries or languages, expand Show Advanced Options and select Merchant Center countries of sale and languages to filter for.
  7. Select the branch you will upload your catalog to.
  8. Click Import.

Cloud Storage

  1. Click Import product catalog to open the Import Data panel.
  2. Choose Product catalog as your data source.
  3. Select the branch you will upload your catalog to.
  4. Choose Retail Product Catalogs Schema as the schema.
  5. Enter the Cloud Storage location of your data.
  6. If you do not have search enabled, select the product levels.

    You must select the product levels if this is the first time you are importing your catalog or you are re-importing the catalog after purging it. Learn more about product levels. Changing product levels after you have imported any data requires a significant effort.

    Important: You can't turn on the search for projects with a product catalog that has been ingested as variants.
  7. Click Import.

BigQuery

  1. Click Import product catalog to open the Import Data panel.
  2. Choose Product catalog.
  3. Select BigQuery as your data source.
  4. Select the branch you will upload your catalog to.
  5. Choose one of the following schemas:
  6. Enter the BigQuery table where your data is located.
  7. Optional: Under Show advanced options, enter the location of a Cloud Storage bucket in your project as a temporary location for your data.

    If not specified, a default location is used. If specified, the BigQuery and Cloud Storage bucket have to be in the same region.
  8. If you do not have search enabled and you are using the Merchant Center schema, select the product level.

    You must select the product level if this is the first time you are importing your catalog or you are re-importing the catalog after purging it. Learn more about product levels. Changing product levels after you have imported any data requires a significant effort.

    Important: You can't turn on the search for projects with a product catalog that has been ingested as variants.
  9. Click Import.

Import your historical user events

To import your historical user events, complete the set of steps for your data source. For more information on historical user events, see Importing historical user events.

Cloud Storage

  1. Click Import user events to open the Import Data panel.
  2. Choose User events.
  3. Select Google Cloud Storage as the data source.
  4. Choose Retail User Events Schema as the schema.
  5. Enter the Cloud Storage location of your data.
  6. Click Import.

BigQuery

  1. Click Import user events to open the Import Data panel.
  2. Choose User events.
  3. Select BigQuery as the data source.

  4. Select the data schema.

  5. Enter the BigQuery table where your data is located.
  6. Optional: Enter the location of a Cloud Storage bucket in your project as a temporary location for your data.
    If not specified, a default location is used. If specified, the BigQuery and Cloud Storage bucket have to be in the same region.
  7. Optional: Under Show advanced options, enter the location of a Cloud Storage bucket in your project as a temporary location for your data.

    If not specified, a default location is used. If specified, the BigQuery and Cloud Storage bucket have to be in the same region.
  8. Click Import.

Create a serving config

A serving config is a serving entity that associates a model or a set of controls that are used to generate your search or recommendation results.

To create a serving config, complete the following steps:

  1. In the Serving configs panel, click Create serving config.
  2. On the Create Serving Config page, choose Search as the product the serving configuration will be used for.
  3. Provide a name for your serving configuration.

    The name must be 1024 characters or less, and can contain only alphanumeric characters, underscores, hyphens, and spaces.
  4. Optional: If needed, update the ID.

    The ID is generated from the name you provide, and must be unique across your project. It must be 50 characters or less, and cannot contain spaces.
  5. Click Continue.
  6. Choose whether to enable dynamic faceting for this serving configuration.
  7. Choose or create serving controls to optimize your searches with.

    For more information on controls, see Creating and managing controls.

The dashboard

When you have completed your initial configuration of your project, the Search for Retail console displays the system state of your Vertex AI Search for retail project. The console enables you to manage resources and monitor activity.

Go to the Search for Retail console

Set up authentication for your app

You must set up authentication so that apps, such as your ecommerce site, can access Vertex AI Search for retail:

  • Service Account. Apps use a service account to authenticate calls to Product. To set up a service account, see Create a service account below.

  • API Key. Apps use an API key for calls to the userEvents.Collect method. You only need to set up this authentication method if you intend to capture user events from users' browsers through a JavaScript pixel or the Google Tag Manager. To set up an API key, see Create an API key below.

Create a service account

  1. Go to the Google Cloud console Credentials page.

  2. Select the project that you are creating a service account in (the project might already be selected).

  3. Click Create credentials and select Service account.

    The Create service account page opens.

  4. Under Service account details, fill in the following fields:

    • Service account name: A display name for your service account.
    • Service account ID: A unique name for your service account. You can use the default ID provided, or replace it with a custom ID.
    • Service account description: Optional. A description of the account.

  5. Click Create and continue to create the service account and proceed to granting the service account access to your project.

  6. Under Grant this service account access to project, add the following roles:

    • Service Accounts > Service Account Token Creator
    • Other > Retail Editor

  7. Optional: To grant service account access to users or groups that need to perform actions as this service account, click Continue and enter the user or group's account information.

  8. Click Done to save your changes.

Add the service account to your local environment

If you want to make calls to Vertex AI Search for retail by using the cURL command-line tool, you'll need to make your service account available in your local environment.

To get a service account key JSON file, follow the instructions in Create and manage service accounts.

The JSON file contains the public/private key for your service account. This JSON file is the only copy of the key for your service account. Be sure to store it in a secure location.

The JSON key file must be stored in a location that is accessible from your app.

cURL uses the gcloud auth application-default print-access-token command to obtain an access token for your service account using the Google Cloud CLI. To download and install the gcloud CLI, see gcloud CLI. If you are using the Cloud Shell, the gcloud CLI is already installed.

The GOOGLE_APPLICATION_CREDENTIALS environment variable will not persist if you close down your command window. To make sure that the variable is set to the path to your service account file when you open a new command window, set the value in an initialization shell script.

  export GOOGLE_APPLICATION_CREDENTIALS=path-to-service-account-json-key-file

Create an API key

An API key is required if you use a JavaScript pixel or a Tag Manager tag to capture user events from users' browsers. For more information about ways to capture user events, see Record real-time user events.

To create an API key for calls to the userEvents.Collect method, complete the following steps:

  1. Go to the Google Cloud console Credentials page.

  2. In the project drop-down at the top of the Google Cloud console page, select your project (the project may already be selected).

  3. Click Create credentials and then select API key. Do not add any website application restrictions. Some user privacy settings are known to not pass the referrer URL.

    • Take note of the generated API key, which you use when calling user event logging.

  4. For increased security, add an API restriction to your API Key to restrict access to the Vertex AI Search for retail service at https://retail.googleapis.com/*.

Examples

Authenticate using a service account (OAuth 2.0)

Here is a Java example of OAuth 2.0 authentication using a service account. More detailed instructions can be found in the authentication documentation. Google has client libraries in 7 languages that you can use to implement OAuth2 authentication in your app. If you prefer to implement the HTTP/REST directly, follow the REST authentication instructions.

In the example, replace your-service-account-json-key-file with the path to the JSON key file for your service account.

// Simple Java example of using Google Cloud OAuth client library.
//
// Please see here for the list of libraries in different languages:
// https://developers.google.com/identity/protocols/OAuth2#libraries
//
// The following example depends on the google api client library.
//
// Maven:
//    <dependency>
//      <groupId>com.google.api-client</groupId>
//      <artifactId>google-api-client</artifactId>
//      <version>1.22.0</version>
//    </dependency>
import com.google.api.client.googleapis.auth.oauth2.GoogleCredential;
import com.google.api.client.googleapis.javanet.GoogleNetHttpTransport;
import com.google.api.client.http.GenericUrl;
import com.google.api.client.http.HttpRequest;
import com.google.api.client.http.HttpRequestFactory;
import com.google.api.client.http.HttpResponse;
import com.google.api.client.http.HttpTransport;
import com.google.api.client.http.json.JsonHttpContent;
import com.google.api.client.json.GenericJson;
import com.google.api.client.json.jackson2.JacksonFactory;
import java.io.FileInputStream;
import java.util.ArrayList;
import java.util.Arrays;
import java.util.Collections;
import java.util.List;

public class RetailApiSample {
  public static final String CREATE_PRODUCT_URL =
     "https://retail.googleapis.com/v2/projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/branches/0/products";

  public static GoogleCredential authorize() throws Exception {
    return GoogleCredential.fromStream(new FileInputStream("your-service-account-json-key-file"))
        .createScoped(Collections.singleton("https://www.googleapis.com/auth/cloud-platform"))
        .setExpirationTimeMilliseconds(new Long(3600 * 1000));;
  }

  // Build an example product.
  public static GenericJson getProduct() {
    GenericJson categories = new GenericJson()
        .set("categories", Arrays.asList("Electronics > Computers", "Laptops"));
    GenericJson priceInfo = new GenericJson()
        .set("currency_code", "USD")
        .set("price", 800.00)
        .set("original_price", 1000.00);

    return new GenericJson()
        .set("name", "projects/PROJECT_NUMBER/locations/global/catalogs/default_catalog/branches/0/products/[ProductName]")
        .set("title", "Sample Laptop")
        .set("description", "Indisputably the most fantastic laptop ever created.")
        .set("categories", categories)
        .set("price_info", priceInfo)
        .set("availability", "IN_STOCK")
        .set("available_quantity", 1219);
  }

  public static void main(String[] args) {
    try {
      GoogleCredential credential = RetailApiSample.authorize();

      HttpTransport httpTransport = GoogleNetHttpTransport.newTrustedTransport();
      HttpRequestFactory requestFactory = httpTransport.createRequestFactory();
      HttpRequest request = requestFactory.buildPostRequest(new GenericUrl(CREATE_PRODUCT_URL),
          new JsonHttpContent(new JacksonFactory(), RetailApiSample.getProduct()));
      credential.initialize(request);
      HttpResponse response = request.execute();
      System.out.println("Response content: " + response.parseAsString());
    } catch (Exception e) {
      e.printStackTrace();
    }
  }
}

What's next