Ads OneShop helps merchants identify opportunities to improve product data and feature adoption, benchmarking against top retailers to maximise performance.
By implementing these recommendations, merchants can improve offer quality, reduce disapprovals, increase advanced feature adoption and drive better auction performance.
| Acronym | Definition |
|---|---|
| ACIT | Advanced Customer Insights Tool / Shopping Insider |
| MEX | Merchant Excellence |
| GMC | Google Merchant Center |
| BQ | BigQuery |
This runbook provides instructions on how to deploy ACIT/Shopping Insider and MEX.
- Create a GCP Project
- Record the Project ID (referenced below as
$PROJECT_ID).
- Record the Project ID (referenced below as
- Enable APIs
- Google Ads API (console link)
- Merchant Center API (console link)
- Service Usage API (console link, used for generating Application Default Credentials)
- Cloud Resource Manager API (console link)
- BigQuery API (console link)
- Configure OAuth
- Consent Screen
- Select appropriate scopes for Ads, GMC, BQ.
- Usually, it's best to select an "internal only" OAuth consent screen.
- Create Desktop Credentials
- Remember to record Client ID and Client Secret.
- Consent Screen
- Create a BigQuery dataset within your project
- (Optional) If you want to automatically update your ACIT data.
- Create a VM
- Get a shell in the VM
- Follow remaining steps using the VM
-
- Standard Access is best, but Basic will work for prototyping/testing.
- As with the OAuth consent screen, it's easiest to get approval if you submit the request for "internal use only" (you are your own client), that is, if you don't plan to open up your app directly (i.e., sign in page) to people outside your company.
- Important: Legal entities are limited to one developer token per company/email domain. If you already have a token somewhere, you must use that token. You must not solicit a developer token from any other companies (i.e., you are an agency)
- Pro Tip: It does not matter what MCC the Developer Token comes from.
- There's an alpha right now for skipping the developer token entirely; all it's used for is identifying which company wrote the calling code.
-
Google Merchant Center
- Google Ads & Google Merchant Center accounts linked together.
NOTE: If you'd like to use a service account with the Ads API and/or the Content API from Merchant Center, reach out to your dedicated technical Google contact.
On a Linux/Mac machine (or VM, or GCP console):
-
Download the code
- Use the UI or any method you prefer, otherwise as below:
git clone https://github.com/google/solutions/ads_oneshop cd ads_oneshop/ -
Ensure you have Go, Python 3.9+ and set up a virtual environment
- Check if Go is installed:
which go
If you do not see any output, install Go from your package manager or https://go.dev/
- Create a virtual env. with the following commands:
python -m venv ./.venv source ./.venv/bin/activate python -m pip install -U pip wheel python -m pip install -e .
-
Set up your GCP CLI
- Run the following if you have not already logged into the gcloud SDK:
gcloud auth login
- Replace $PROJECT_ID with your project id and run:
gcloud auth application-default login --billing-project=$PROJECT_ID --scopes="https://www.googleapis.com/auth/cloud-platform,https://www.googleapis.com/auth/userinfo.email,openid,https://www.googleapis.com/auth/content,https://www.googleapis.com/auth/sqlservice.login"
-
Generate a Refresh Token for Google Ads using this Colab.
-
Follow the instructions here and set the following in google-ads.yaml.
- Save it in your home directory:
- developer_token
- use_proto_plus: false
- client_id:
- client_secret:
- refresh_token
- Set the following environment variables:
export CUSTOMER_IDS=123,456 # must be top-level for now
export MERCHANT_IDS=456,789
export STAGING_DIR=$HOME/choose_any_other_existing_folder # if you want to set up multiple runs, it’s recommended to set this directory differently for each.
export PROJECT_NAME=your-project-name # This is PROJECT_ID
export DATASET_NAME=your_project_dataset
export DATASET_LOCATION=US
export ADMIN=true
export GOOGLE_ADS_CONFIGURATION_FILE_PATH=$HOME/google-ads.yaml
export REPORT_NAME="ACIT: Advanced Commerce Insights Tool"NOTE: The IDs can be whatever length; they need to be without hyphens or other punctuation. The comma is to delimit them if there are more than one.
TIP: optionally, you can save the above variables in a file, and load it to
your shell environment with an replacement for $YOUR_ENV_FILE bash set -a && source $YOUR_ENV_FILE && set +a
- **From the root repository, run:
acit/run_acit.shOnly follow these steps if you want to automate the run of ACIT
If you've been doing these steps on a machine that will be refreshing ACIT data automatically, these are steps to get this done:
- Scheduling this to run with a cron job
- The Code should be cloned to a directory, such as ~/ads_oneshop (assuming this directory will be used for the rest of the instructions)
Create a data directory
mkdir -p $HOME/acit_dataTo set up the Python environment, run:
cd ~/ads_oneshop && python -m venv .venv && source ./.venv/bin/activate && python -m pip install --upgrade -r acit/requirements.txtIn your workspace home folder, create a file named "acit.env.prod" (or anything you like) and paste it in the following variables, which will be sourced as environment variables for the entrypoint:
CUSTOMER_IDS=123,456 # must be top-level for now
MERCHANT_IDS=456,789
STAGING_DIR=$HOME/choose_any_other_existing_folder
PROJECT_NAME=your-project-name
DATASET_NAME=your_project_dataset
DATASET_LOCATION=US
ADMIN=trueto bootstrap everything together, let's create a wrapper script in the home directory called "acit_wrapper.sh", which can be used in a cron job:
#!/bin/bash
set -e
echo "Loading environment variables from file $1"
set -a
source $1
set +a
echo "Running ACIT"
cd $HOME/advanced_commerce_insights_tool
source ./.venv/bin/activate
acit/run_acit.shFinally, run:
chmod +x ~/acit_wrapper.shInitial Run
To run, all you have to do is execute
bash ~/acit_wrapper.sh ~/acit.env.prod- To be able to access the template below, join the
Ads OneShop public Google group.
- The group is open, no need to request access.
- Just press 'Join Group' when logged in with a Google Account.)
- Make a Copy of the template.
- Update data sources to use BQ dataset.
- Download and save the benchmark files.
- Go to BigQuery in GCP and click on the dataset's 3 dot menu
- Follow the example below and upload the benchmark details and values files
- Please follow the recommended names:
- MEX_benchmark_details
- MEX_benchmark_values
- (Repeat the example below for the values file as well)
- After the files have been uploaded successfully, verify that those tables have been created. Return to your command line and follow the instructions below.
From the root repository, run: bash extensions/merchant_excellence/run_acit_mex.sh
- Load benchmark JSONs.
- To gain access to the template, ensure you've joined the public group as pointed out previously.
- Copy the [template](https://lookerstudio.google.com/c/u/0/reporting/c9b47c32-f5b8-4ad5-a59f-495b0e58dbc8/page/ 2RkaD)
- Update data sources to use BQ dataset.

