Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: add first readme draft #8

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs: add first readme draft #8

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
170 changes: 158 additions & 12 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,16 +11,97 @@

Install the latest release of the cli:

````bash
```bash
$ brew update
$ brew install foomo/tap/sesamy-cli
````
```

## Caveats

You might need to increase your Google Tag Manager API quotas, since they are limited to 15 r/m by default.

Currently the sesamy-cli doesn't submit the changes automatically. This needs to be done manually in Google Tag Manager

## How to Contribute

Make a pull request...

## License

Distributed under MIT License, please see license file within the code for more details.

## Usage
## Glossary

As some terms for Google Analytics and GTM events and ressources can be confusing we want to clarify the following definitions that are used in this README:

- Google Tag Manager: A configuration interface for different kind of containers (Web, Server etc.). The server container configuration is represented by a Tagging server
- Web container: This is a tagging container hosted by Google and can be configured via the Google Tag Manager
- Tagging server: This is a server that you setup yourself based on an docker image from Google that can receive and process "/g/collect" and other requests. You have to set environment variables to connect your server with the Google Tag Manager configuration interface
- Preview server: Similar to the tagging server, with the same docker image, but different environment variables to be needed. This server provides you with a Web UI to preview incoming and outgoing requests of the Tagging server

## What problem does it solve?

### Automate the creating of web and server container ressources

If tracking events need params that are not standard or e-commerce (enhanced) in Google Analytics then you have to configure those events and params on the Web container GA4 Tag manually. Same is true if it is a standard parameter, but not part of the recommended parameters of the event type.

In order to associate a parameter with an event, the parameter needs to be configured as an additional ressource in the web container by creating a new datalayer variable. The data layer variables name needs to start with "eventModel." e.g. "eventModel.user_group".

Sesamy CLI automates this process

### Guarantee typesafety when tracking events with gtag()

Auto generate typescript types based on the event structs that you define with sesamy-go (https://github.com/foomo/sesamy-go/). When using gtag() the generated types make sure that you get code completion and type checks on gtag() calls

```typescript
//common.tsx

import { EventNames, EventParams } from "events";

export const gtag = (name: EventNames, params: EventParams) => {
window.dataLayer = window.dataLayer || [];
window.gtag =
window.gtag ||
function () {
// @ts-ignore
// eslint-disable-next-line prefer-rest-params
window.dataLayer?.push(arguments);
};
window.gtag("event", name, params);
};
```

Add a `sesamy.yaml` configurtion
```typescript
//e.g. checkout.tsx

gtag("begin_checkout", {
currency: props.summary.total.currency,
value: props.summary.total.cents / 100,
items: mapCartItems(props.items),
} as BeginCheckout);
```

## Configuration

You need a `sesamy.yaml` configuration. Check out the tygo documentation (https://github.com/gzuidhof/tygo) for additional, optional configurations.

Explanation:

- account_id: Open Server container in tagmanager -> url parameter `accountId`
- container_id: Open Server/web container in tagmanager -> url param: `container`
- workspace_id: Open Server/web container in tagmanager -> url param: `workspace`
- ga4.measurement_id: The Google Analytics measurment ID
- gtm.[server/web].measurement_id: The identifier of the web or server container
- credentials_file: You need a credentials.json from a Google Cloud Platform service account in order to connect to the web and server container. You need to register that user with edit rights on the web and the server container
- server_container_url: URL of your server container (has to be https)

<br>

```yml
# sesamy.yaml

# NOTE: needs to be placed next to the go.mod file

```yaml
google:
ga4:
measurement_id: G-PZ5ELRCR31
Expand All @@ -38,22 +119,87 @@ google:
measurement_id: GTM-57BHX34G

credentials_file: ./tmp/google_service_account_creds.json
server_container_url: http://sst.my-domain.com/

events:
# Generates typescript types
typescript:
packages:
- path: "github.com/foomo/sesamy-cli/_example/server"
output_path: "./_example/client/types.d.ts"
indent: "\t"

# Provisions backend structs. Exclude allnon event structs
tagmanager:
packages:
- path: "github.com/foomo/sesamy-cli/_example/server"
output_path: "./_example/client/types.d.ts"
exclude_files:
- item.go
```

## Caveats
<br>

Currently to be created manually: typescript.go file that exports all the event names and the event parameters

```go
// typescript.go

package event

//tygo:emit
var _ = `export type EventNames =
| 'add_payment_info'
| 'add_shipping_ingo'
| 'add_to_cart'
| 'add_to_wishlist'
| 'ce_account_signup'
| 'ce_login'
| 'purchase'
| 'refund'
| 'remove_from_cart'
| 'select_item'
| 'view_cart'
| (string & NonNullable<unknown>);

export type EventParams =
| AddPaymentInfo
| AddShippingInfo
| AddToCart
| AddToWishlist
| CEAccountSignup
| CELogin
| Purchase
| Refund
| RemoveFromCart
| SelectItem
| ViewCart;
```

You might need to increase your Google Tag Manager API quotas, since they are limited to 15 r/m by default.
## How to run

## How to Contribute
The following two command setup Google Tag Manager ressources in the server and in the web container

Make a pull request...
```bash
sesamy tagmanager server
```

## License
Creates following ressources on the server container

Distributed under MIT License, please see license file within the code for more details.
- Folder Sesamy
- Variable for MeasurementID
- "Google Tag Manager Web Container" client
- "GA4" client
- "GA4" trigger
- "GA4" tag -> "GA4 trigger" is used here

<br>

```bash
sesamy tagmanager client
```

Creates following ressources on the web container

- Folder Sesamy
- Variable for MeasurementID
- Event params for GA4 Tag, Tag, Trigger and Variables
Loading