Git Product home page Git Product logo

disapproved-ads-auditor's Introduction

Disapproved Ads Auditor - a scaled ad auditing tool

Advertisers operating at scale need a scalable solution to review policy violating ads across their accounts so they can ensure compliance with Google’s Ad Policies. As Google introduces more policies and enforcement mechanisms, advertisers need to continue checking their accounts to ensure they comply with Google’s Ads Policies.

The tool is used to review at scale all disapproved ads across advertisers’ accounts in order to allow advertisers to proactively audit their account at scale and take learnings from the results (how to reduce submission of ads potentially violating Google Ads Policies).

The tool is based on a Python script, which can be run in either of the following modes:

  • “Audit Mode”- export an output of disapproved ads across your accounts
  • “Remove Mode” - deletes disapproved ads and logs their details

Project owners


Disclaimer

This is not an officially supported Google product. Copyright 2021 Google LLC. This solution, including any related sample code or data, is made available on an “as is,” “as available,” and “with all faults” basis, solely for illustrative purposes, and without warranty or representation of any kind. This solution is experimental, unsupported and provided solely for your convenience. Your use of it is subject to your agreements with Google, as applicable, and may constitute a beta feature as defined under those agreements. To the extent that you make any data available to Google in connection with your use of the solution, you represent and warrant that you have all necessary and appropriate rights, consents and permissions to permit Google to use and process that data. By using any portion of this solution, you acknowledge, assume and accept all risks, known and unknown, associated with its usage, including with respect to your deployment of any portion of this solution in your systems, or usage in connection with your business, if at all.


Run modes

disapproved-ads-auditor tool is a python command-line tool that can run in one of the following modes:

  • “Audit Only Mode”- export the relevant ads without deleting them;
  • “Audit + Remove Mode” - export and delete the relevant ads. There are a few output files (see here) which are saved locally under the “output” folder and optionally on BigQuery as well (“dissaproved_ads_auditor” dataset).

Diagram of The tool's functionality



Selecting the relevant policies

  • This json contains two lists used by the disapproved-ads-auditor tool.
  • Leave both lists empty if you want to audit ads labeled with all policy labels.
  • Fill out the first list if you want to hand pick only relevant policies.
  • Fill out the second list if you want to hand pick policies to be excluded from the audit.
Example A:
inclusion: [drugs, weapons] - any ad with a policy topic that contains any of the words "drugs" or "weapons" to be audited and / or removed.
exclusion: []

Example B:
inclusion: []
exclusion: [destination] - any ad which has only topics that contains the word "destination" should be skipped and not audited and / or removed.


Getting the keys/tokens

Follow the below text, or this official video or non-official video

1.1. Get Google Ads Developer Token. Add developer token id to google-ads.yaml file.

1.2. Generate OAuth2 credentials for desktop application

* Click the download icon next to the credentials that you just created and save file to your computer

* Add client_id and client_secret value to `google-ads.yaml` file

1.3. Download python source file to perform desktop authentication

```
curl -0 https://raw.githubusercontent.com/googleads/google-ads-python/868bf36689f1ca4310bdead9c46eed61b8ad1d11/examples/authentication/authenticate_in_desktop_application.py
```

1.4. Run desktop authentication with downloaded credentials file: python authenticate_in_desktop_application.py --client_secrets_path=/path/to/secrets.json

* Copy generated refresh token and add it to `google-ads.yaml` file.

1.5. Enable Google Ads API in your project

1.6. Add login_customer_id and client_customer_id (MMC under which Developer token was generated) to google-ads.yaml. ID should be in 11111111 format, do not add dashes as separator.



Setup

  1. Using the tokens and keys from the above section, fill them in "src/secret_keys/google-ads.yaml" file
client_customer_id:
client_id:
client_secret:
developer_token:
login_customer_id:  # The MCC id 
refresh_token:
use_proto_plus: True
  1. Install google ads API
pip3 install google-ads --upgrade

steps 3-5 are optional: save audit to BQ in addition to local files

  1. Install BigQuery API
pip3 install --user --upgrade google-cloud-bigquery
  1. Create a GCP service-account (type: desktop-client) and download its key. See GCP doc. Give that service-account bigquery.user role (BigQuery Job User)

  2. Set an environment variable:

export GOOGLE_APPLICATION_CREDENTIALS = <YOUR_SERVICE_ACCOUNT_KEY>


Running

  1. Run this while <ACCOUNT_ID> is the top MCC to run from.
python3 main.py -id <ACCOUNT_ID>

Tip: How to fill login_customer_id: field in google-ads.yaml

A. If <ACCOUNT_ID> is an MCC, it should appear in this field.

B. If <ACCOUNT_ID> is a single-account, its parent MCC should appear this field.


Flags

python3 main.py -id <ACCOUNT_ID> -rm
  • -rm | --remove_ads - Audits and removes the ads.

Less common flags (if uploading to BQ)
  • -bq | --write_to_bq - Audits in BQ in addition to local file.
  • -ddb | --delete_db - Deletes the BQ tables which are relevant to the tool.
  • -clean_bq | --clean_outdated_bq -Deletes outdated rows in BQ.

Python reminder

  • Redirect tool's output to file:
    python3 main.py > logFile

Output schemas (CSV in local files / tables on BQ)

  • Local result files, are under "output" folder.
  • Under BQ dataset "disapproved-ads-auditor" (optional).

"AllAccounts"

Lists all the subMCC and sub accounts that were scanned

all accounts

account_id hierarchy: Mcc_SubMcc_SubAccount. timestamp: when scanning all the sub accounts finished. session_id: identifies the last run and join with other tables.


"AdsToRemove"

Lists all the ads to be removed including all the data required for re-uploading the ads (if they were removed).

Ads to remove

Based on Google Ads ad_group_ad report

  • ad_id
  • ad_type
  • ad_group_id
  • campaign_id
  • hierarchy: Mcc_SubMcc_SubAccount.
  • final_urls: The list of possible final URLs after all cross-domain redirects for the ad.
  • policy_topics
  • evidences
  • mandatory_data
  • timestamp: when the audited_status was set.
  • audited_status: SCANNED, REMOVED, FAILED_TO_REMOVE. Another row is usually added for status change instead of being updated.
  • account_id
  • session_id: identifies the last run and join with other tables.
  • removal_error: Google server error in case audited_status = FAILED_TO_REMOVE

"PerMccSummary"

Sums per top-MCC level. Accomulate all the data of the next 'perAccountSammry'

per mcc summary

  • account_id
  • total_sub_accounts: total # of sub accounts.
  • top_mcc_total_ads_to_remove: total # of ads to remove.
  • timestamp: when the scan for the whole mcc ended.
  • session_id: identifies the last run and join with other tables.

"PerAccountSummary"

When finished processing an account, it sums the numbers of ads to be removed, ads that have been removed.

per account

  • account_id
  • ads_to_remove_count: total # of ads to remove.
  • timestamp: when scan for this account ended.
  • session_id: identifies the last run and join with other tables.

Example for relevant SQL queries (using session id for joinning fields)

SQL query

Notes and recommendations:

  • Run the code as a cron-job over the cloud.
  • Monitor that cron-job with mail alerts when it fails to run.
  • The code does 3 retries if it crashes.
  • Google BQ API allows a built-in retry mechanism (see BQ query API)

Troubleshooting

ValueError: A required field in the configuration data was not found. The required fields are: ('developer_token',)

or

ValueError: The client library configuration is missing the required "use_proto_plus" key. Please set this option to either "True" or "False". For more information about this option see the Protobuf Messages guide: https://developer
s.google.com/google-ads/api/docs/client-libs/python/protobuf-messages
  • Solution: Check you’ve filled the google-ads.yaml file correctly
Request with ID "XXXXX" failed with status "PERMISSION_DENIED" and includes the following errors:
        Error with message "User doesn't have permission to access customer. Note: If you're accessing a client customer, the manager's customer id must be set in the 'login-customer-id' header. See https://developers.google.com/goo
gle-ads/api/docs/concepts/call-structure#cid".
  • Solution: make sure login_customer_id : in the yaml file contains the relevant MCC id.

License

Apache Version 2.0 See LICENSE

disapproved-ads-auditor's People

Contributors

duvall avatar elad2109 avatar nkal-google avatar pgilmon avatar

Stargazers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Watchers

 avatar  avatar  avatar  avatar  avatar  avatar  avatar  avatar

Forkers

duvall kb117-star

Recommend Projects

  • React photo React

    A declarative, efficient, and flexible JavaScript library for building user interfaces.

  • Vue.js photo Vue.js

    🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.

  • Typescript photo Typescript

    TypeScript is a superset of JavaScript that compiles to clean JavaScript output.

  • TensorFlow photo TensorFlow

    An Open Source Machine Learning Framework for Everyone

  • Django photo Django

    The Web framework for perfectionists with deadlines.

  • D3 photo D3

    Bring data to life with SVG, Canvas and HTML. 📊📈🎉

Recommend Topics

  • javascript

    JavaScript (JS) is a lightweight interpreted programming language with first-class functions.

  • web

    Some thing interesting about web. New door for the world.

  • server

    A server is a program made to process requests and deliver data to clients.

  • Machine learning

    Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.

  • Game

    Some thing interesting about game, make everyone happy.

Recommend Org

  • Facebook photo Facebook

    We are working to build community through open source technology. NB: members must have two-factor auth.

  • Microsoft photo Microsoft

    Open source projects and samples from Microsoft.

  • Google photo Google

    Google ❤️ Open Source for everyone.

  • D3 photo D3

    Data-Driven Documents codes.