Skip to main content

An object-oriented helper library wrapping the Tag Manager API Client Library for Python.

Project description

GTM Manager (WIP)

Build Status Build Status Documentation Status Documentation Status

An object-oriented helper library wrapping the Tag Manager API Client Library for Python for the Google Tag Manager API.

pip3 install gtm_manager

Documentation: https://gtm-manager.readthedocs.io

Installation from Source

python3 setup.py sdist
pip3 install gtm_manager --find-links $(pwd)/dist/

Getting Started

Use a Google account to create application credentials, download the JSON file and put it in the same directory as your script with the name client_secret.json. During the first execution of any API-dependent library code, you will be prompted to perform the auth flow.

from gtm_manager import GTMManager

accounts = GTMManager().list_accounts()

for account in account:
    print(account.name)

Authentication

This library currently only supports user-based oauth crendentials. Service accounts can not be used.

When using any of the classes from the resources that require loading data from the Google Tag Manager API, the library will look for an existing in OAuth token in the credentials file or prompt the user to authorize which requires a client secret file.

Client Secrets

The Google OAuth flows requires you to provide a client id and secret in the from of a JSON file. You can create these in any Google Cloud or Google Developer project:

  1. Open the Google API Console Credentials page.
  2. From the project drop-down, choose Create a new project, enter a name for the project, and optionally, edit the provided Project ID. Click Create.
  3. On the Credentials page, select Create credentials, then select OAuth client ID.
  4. You may be prompted to set a product name on the Consent screen; if so, click Configure consent screen, supply the requested information, and click Save to return to the Credentials screen.
  5. Select Other for the Application type, and enter any additional information required.
  6. Click Create.
  7. On the page that appears, you can download client id and secret as a JSON file.

By default, the gtm_manager will look for client id and secret in the file client_secret.json. You can overwrite the default to any file name with absolute or relative path:

gtm_manager.CLIENT_SECRET_FILE = "my_client_secret.json"

Credentials File

OAuth user credentials will be stored in plain text. During every invocation of API-dependent library code, the gtm_manager will try to open this file for credentials. If no credentials are present, a new auth flow with the provided client id and secret will be started.

The auth flow will request offline access from the user providing the script with an oauth refresh token to continue using the file as long as the user not explicitly revokes access.

By default, the gtm_manager will look for existing and store new credentials in the file auth_credentials.json. You can overwrite the default to any file name with absolute or relative path:

gtm_manager.CREDENTIALS_FILE_NAME = "my_auth_credentials.json"

Scopes

The Google OAuth system uses scopes to request different types of account access from a user. The Google Tag Manager API uses seven different scopes. Different API methods requires different scopes. Details can be found in the Google Tag Manager API Reference. After initial authorisation, the stored credentials can not extend or chang their scope.

By default, the gtm_manager will request all seven scopes from a user during the auth flow. For ease of use, all scopes are defined as constants under gtm_manager.GoogleTagManagerScopes.

You can overwritte the requested scopes to an array of scope strings:

gtm_manager.AUTH_SCOPES = [
    gtm_manager.GoogleTagManagerScopes.EDIT_CONTAINERS,
    gtm_manager.GoogleTagManagerScopes.PUBLISH,
]

Auth Best Practice

Even though the default settings get you up and running quickly, it is recommended to always explicitly set your settings. Every gtm_manager script should therefore contain the following code block:

# explicitly set the location of your client secret file
gtm_manager.CLIENT_SECRET_FILE = "my_client_secret.json"
# explicitly set the location of your credentials file
gtm_manager.CREDENTIALS_FILE_NAME = "my_auth_credentials.json"
# explicitly set the required scopes
gtm_manager.AUTH_SCOPES = [
    gtm_manager.GoogleTagManagerScopes.EDIT_CONTAINERS,
    gtm_manager.GoogleTagManagerScopes.PUBLISH,
]

Usage Examples

The gtm_manager speeds up interaction working with the Google Tag Manager API for various use cases. Some of these use cases are demoed below. If you are missing a use case, please open an issue and we will be happy to help and extend the demo!

List all GTM containers in an account

# import gtm_manager
# from gtm_manager.manager import GTMManager

# gtm_manager.CLIENT_SECRET_FILE = "my_client_secret.json"
# gtm_manager.CREDENTIALS_FILE_NAME = "my_auth_credentials.json"
# gtm_manager.AUTH_SCOPES = [gtm_manager.GoogleTagManagerScopes.READONLY]

accounts = GTMManager().list_accounts()

for account in accounts:
    print(account.name)

Add a new tag, trigger, variable to all containers in an account

# import gtm_manager
# from gtm_manager.account import GTMAccount

# gtm_manager.CLIENT_SECRET_FILE = "my_client_secret.json"
# gtm_manager.CREDENTIALS_FILE_NAME = "my_auth_credentials.json"
# gtm_manager.AUTH_SCOPES = [
#     gtm_manager.GoogleTagManagerScopes.EDIT_CONTAINERS,
#     gtm_manager.GoogleTagManagerScopes.PUBLISH,
#     gtm_manager.GoogleTagManagerScopes.EDIT_CONTAINERVERSIONS,
# ]

account = GTMAccount(path="accounts/1234")
containers = account.list_containers()

for container in containers:
    workspace = container.create_workspace("Global Update Workspace")

    trigger = workspace.create_trigger(
        {
            "name": "Custom - Generic Event",
            "type": "CUSTOM_EVENT",
            "customEventFilter": [
                {
                    "type": "EQUALS",
                    "parameter": [
                        {"type": "TEMPLATE", "key": "arg0", "value": "{{_event}}"},
                        {"type": "TEMPLATE", "key": "arg1", "value": "Generic Event"},
                    ],
                }
            ],
        }
    )

    variable = workspace.create_variable(
        {
            "name": "cjs.randomNumber",
            "type": "jsm",
            "parameter": [
                {
                    "type": "TEMPLATE",
                    "key": "javascript",
                    "value": "function() {\n  return Math.random();\n}",
                }
            ],
        }
    )

    workspace.create_tag(
        {
            "name": "HTML - Hello Log",
            "type": "html",
            "parameter": [
                {
                    "type": "TEMPLATE",
                    "key": "html",
                    "value": '<script>\n  console.log("Hello World")\n</script>',
                }
            ],
            "firingTriggerId": [trigger.triggerId],
        }
    )

    version = workspace.create_version("Global Update Workspace")
    version.publish()

Update a Variable on a Tag

# import gtm_manager
# from gtm_manager.account import GTMAccount

# gtm_manager.CLIENT_SECRET_FILE = "my_client_secret.json"
# gtm_manager.CREDENTIALS_FILE_NAME = "my_auth_credentials.json"
# gtm_manager.AUTH_SCOPES = [
#     gtm_manager.GoogleTagManagerScopes.EDIT_CONTAINERS,
#     gtm_manager.GoogleTagManagerScopes.EDIT_CONTAINERVERSIONS,
#     gtm_manager.GoogleTagManagerScopes.PUBLISH,
# ]

account = GTMAccount(path="accounts/1985550951")
containers = account.list_containers()

for container in containers:
    workspace = container.create_workspace("Global Update Workspace")

    tag = workspace.get_tag_by_name("UA - Pageview")

    doubleClick_param = tag.parameter_dict["doubleClick"]
    doubleClick_param.value = "false"

    tag.update(parameter=[doubleClick_param])

    version = workspace.create_version("Global Update Workspace")
    version.publish()

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

gtm-manager-0.3.0.tar.gz (19.4 kB view details)

Uploaded Source

Built Distribution

gtm_manager-0.3.0-py3-none-any.whl (29.1 kB view details)

Uploaded Python 3

File details

Details for the file gtm-manager-0.3.0.tar.gz.

File metadata

  • Download URL: gtm-manager-0.3.0.tar.gz
  • Upload date:
  • Size: 19.4 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/2.0.0 pkginfo/1.5.0.1 requests/2.22.0 setuptools/41.4.0 requests-toolbelt/0.9.1 tqdm/4.36.1 CPython/3.7.0a4+

File hashes

Hashes for gtm-manager-0.3.0.tar.gz
Algorithm Hash digest
SHA256 59b27964861ce7caf932d5fb6656d484c0fe49bc2ed7465bc828eed2e94779f5
MD5 05137c41801f9a25326aa4d1af46cb55
BLAKE2b-256 4ba5be2c29fbc5eb77d760721fe4597a8bf138f5efbec9f130f5041ff1d4e161

See more details on using hashes here.

File details

Details for the file gtm_manager-0.3.0-py3-none-any.whl.

File metadata

  • Download URL: gtm_manager-0.3.0-py3-none-any.whl
  • Upload date:
  • Size: 29.1 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/2.0.0 pkginfo/1.5.0.1 requests/2.22.0 setuptools/41.4.0 requests-toolbelt/0.9.1 tqdm/4.36.1 CPython/3.7.0a4+

File hashes

Hashes for gtm_manager-0.3.0-py3-none-any.whl
Algorithm Hash digest
SHA256 389fed6b4d34f91eb3ee55fa315335211de0b29a5ad3d9cdb24e430379651ad0
MD5 17b440cf9b6e8932093bb14e231854fc
BLAKE2b-256 9611a42b72ce5727b2616844b4b61e2077e0558680a36c5e92757c4f20a7ae7f

See more details on using hashes here.

Supported by

AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Pingdom Monitoring Sentry Error logging StatusPage Status page