search

google-marketing-solutions / Tightlock

Apache License 2.0
32 stars 15 forks source link

readme

Copyright Google LLC. Supported by Google LLC and/or its affiliate(s). 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 and any processing of data by Google, 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. With respect to the entrustment of personal information to Google, you will verify that the established system is sufficient by checking Google's privacy policy and other public information, and you agree that no further information will be provided by Google.

Tightlock - First-Party Data Tool

Named after the automatic joining mechanism used between train cars, Tightlock is an open source tool that can be used to transport first-party data to Google ads platforms (e.g., Ads, Google Marketing Platform) via Google APIs.

Some examples of connections that are available through Tightlock are:

Tightlock serves as a cloud-agnostic pipeline tool to pull data from a variety of customer sources (e.g., BigQuery, Cloud Storage, S3 etc) for transfer into Google APIs.

You can learn more about Tightlock by watching this introduction video.

Installation

Tightlock runs on Docker, so it can be deployed virtually anywhere. You can find instructions below on running on local machines and deploying in GCP or AWS with Terraform. Similar Terraform installer for Azure is coming soon.

Running locally

See Developer Workflow for detailed instructions for running Tightlock locally for development.

GCP Deploy

You can click the button below to start deployment of Tightlock in GCP. You can find detailed instructions for GCP deployment here.

Open in Cloud Shell

AWS Deploy

For deploying in AWS, follow instructions here.

Azure Deploy

COMING SOON

General usage

Below, you will find simplified instructions for using Tightlock. For a more detailed guide, refer to this presentation.

Workspace creation

The recommended way to configure connections in Tightlock is to link your backend instance in the 1PD Scheduler tool: https://1pd-scheduler.dev

In the tool:

  1. Sign-in using a Gmail / Google Workspaces account
  2. If you don't have a workspace yet, create a new one, choosing a name and providing the connection code that was generated during the deployment process.
  3. Once you have a workspace selected, all connections created in this workspace context will be using the backend instance tied to the connection code that was provided.

Creating connections

Connections are the core concept of Tightlock. A connection is defined by a source of data, a destination (tipically, a Google API) and a schedule (or None).

You can create new connections by:

Tightlock API

Tightlock communicates with https://1pd-scheduler.dev by using a REST API. This API can also be directly accessed by customers that are not interested in configuring the backend using the UI.

You can find a quick summary of the main actions that are available in the API.

Note: Bear in mind that the default deployment of Tightlock has a security measure of limiting the IPs that can call the API. If you want to use the API direclty, make sure to change this configuration or call the API using an internal IP address.


Create a new config

POST /api/v1/configs #### **Payload** example.json file: ```json { "label": "Example BQ to GA4 App", "value": { "external_connections": [], "sources": { "example_bigquery_table": { "type": "BIGQUERY", "dataset": "bq_dataset_example_name", "table": "bq_table_example_name" } }, "destinations": { "example_ga4_app": { "type": "GA4MP", "payload_type": "firebase", "api_secret": "fake_api_secret", "firebase_app_id": "fake_firebase_app_id" } }, "activations": [ { "name": "example_bq_to_ga4mp_app_event", "source": { "$ref": "#/sources/example_bigquery_table" }, "destination": { "$ref": "#/destinations/example_ga4_app" }, "schedule": "@weekly" } ], "secrets": {}, } } ``` Bear in mind that "label" must be unique. #### **Responses** > | http code | content-type | response | > |---------------|-----------------------------------|---------------------------------------------------------------------| > | `200` | `application/json` | `Configuration created successfully` | > | `409` | `application/json` | `{"code":"409","message":"Config label already exists"}` | #### **Example cURL** > ```javascript > curl -H "Content-Type: application/json" -X POST -H 'X-Api-Key: {EXAMPLE_API_KEY}' {ADDRESS}:8081/api/v1/configs -d @example.json > ```


Get the current config

GET/api/v1/configs:getLatest #### **Payload** None #### **Responses** > | http code | content-type | response | > |---------------|-----------------------------------|---------------------------------------------------------------------| > | `200` | `application/json` | Config in JSON format | | #### **Example cURL** > ```javascript > curl -H "Content-Type: application/json" -H 'X-Api-Key: {EXAMPLE_API_KEY}' {ADDRESS}:8081/api/v1/configs:getLatest > ```


Trigger an existing connection

GET/api/v1/connection:{connection_name} #### **Payload** > | name | type | data type | description | > |-----------|-----------|-------------------------|-----------------------------------------------------------------------| > | connection_name | required | str | Target connection > | dry_run | not required | int | Whether or not to do a dry-run for the target connection (0 is false and 1 is true) #### **Responses** > | http code | content-type | response | > |---------------|-----------------------------------|---------------------------------------------------------------------| > | `200` | `application/json` | Trigger successful | | #### **Example cURL** > ```javascript > curl -X POST -H 'X-API-Key: {EXAMPLE_API_KEY}' -H 'Content-Type: application/json' -d '{"dry_run": 0}' -o - -i {ADDRESS}:8081/api/v1/activations/activation_name:trigger > ```

Privacy Notice

[!NOTE] By using this solution you agree for usage data to be collected automatically. If you don't want this information to be collected you can opt-out during installation or refrain from using the solution.

The information we collect includes:

Log and Usage Data: Log and usage data is service-related, diagnostic, usage, and performance information automatically collected when connections created in the Tightlock backend are run. This data may include non-personally identifiable information such as:

We do not collect any personal information such as email, name, or phone number.

We process your logs and usage data to identify aggregated trends and issues and to better understand how our solutions are being employed so we can improve them.