feat: custom mixpanel template

README.md

@@ -193,6 +193,12 @@ googleTag:
 googleAnalytics:
   # Enable provider
   enabled: true
+  # Custom tag template settings
+  templates:
+    # Path to a custom json request value variable template file, defaults to the embedded one
+    jsonRequestValueVariable: ''
+    # Path to a custom gtag client template file, defaults to the embedded one
+    gtagClient: ''
   # Google Consent settings
   googleConsent:
     # Enable consent mode
@@ -294,6 +300,10 @@ umami:
   websiteId: ''
   # Endpoint url of the umami api
   endpointUrl: https://umami.your-domain.com
+  # Custom tag template settings
+  templates:
+    # Path to a custom tag template file, defaults to the embedded one
+    tag: ''
   # Google Consent settings
   googleConsent:
     # Enable consent mode
@@ -320,6 +330,12 @@ criteo:
   partnerId: 123456
   # Criteo applicaiton id
   applicationId: com.foomo
+  # Custom tag template settings
+  templates:
+    # Path to a custom events api tag template file, defaults to the manually installed one
+    eventsApiTag: ''
+    # Path to a custom user identification template file, defaults to the manually installed one
+    userIdentification: ''
   # Google Tag Manager server container settings
   serverContainer:
     # Path to the go.mod file
@@ -347,6 +363,10 @@ facebook:
   apiAccessToken: ''
   # Code used to verify that your server events are received correctly by Conversions API
   testEventToken: ''
+  # Custom tag template settings
+  templates:
+    # Path to a custom conversions api tag template file, defaults to the manually installed one
+    conversionsApiTag: ''
   # Google Tag Manager server container settings
   # Google Consent settings
   googleConsent:
@@ -377,6 +397,14 @@ emarsys:
   enabled: true
   # Emarsys merchant id
   merchantId: ''
+  # Custom tag template settings
+  templates:
+    # Path to a custom web extend tag template file, defaults to the embedded one
+    webExtendTag: ''
+    # Path to a custom initialization client template file, defaults to the embedded one
+    initializationClient: ''
+    # Path to a custom initialization tag template file, defaults to the embedded one
+    initializationTag: ''
   # Google Consent settings
   googleConsent:
     # Enable consent mode
@@ -403,6 +431,10 @@ tracify:
   token: ''
   # Tracify customer site id
   customerSiteId: ''
+  # Custom tag template settings
+  templates:
+    # Path to a custom tag template file, defaults to the embedded one
+    tag: ''
   # Google Consent settings
   googleConsent:
     # Enable consent mode
@@ -436,6 +468,10 @@ cookiebot:
   # Name of the manually installed Cookiebot CMP tag template
   # "https://tagmanager.google.com/gallery/#/owners/cybotcorp/templates/gtm-templates-cookiebot-cmp
   templateName: Cookiebot CMP
+  # Custom tag template settings
+  templates:
+    # Path to a custom cmp tag template file, defaults to the manually installed one
+    tag: ''
   # Cookiebot id
   cookiebotId: ''
   # CDN Region (eu, com)
@@ -463,6 +499,12 @@ cookiebot:
 utm:
   # Enable provider
   enabled: true
+  # Custom tag template settings
+  templates:
+    # Path to a custom attribution variable template file, defaults to the embedded one
+    attributionVariable: ''
+    # Path to a custom cookie writer tag template file, defaults to the embedded one
+    cookieWriterTag: ''
   # Google Consent settings
   googleConsent:
     # Enable consent mode
@@ -476,6 +518,10 @@ mixpanel:
   enabled: true
   # Project Token
   projectToken: ''
+  # Custom tag template settings
+  templates:
+    # Path to a custom tag template file, defaults to the embedded one
+    tag: ''
   # Google Consent settings
   googleConsent:
     # Enable consent mode
@@ -515,6 +561,10 @@ pinterest:
   apiAccessToken: ''
   # Enable test mode
   testModeEnabled: false
+  # Custom tag template settings
+  templates:
+    # Path to a custom conversions tag template file, defaults to the manually installed one
+    tag: ''
   # Google Consent settings
   googleConsent:
     # Enable consent mode

docs/CONTRIBUTING.md

@@ -8,8 +8,8 @@ Thank you for your interest in contributing to our project! This guide will help
 2. Create a new branch: `git checkout -b feature/your-feature-name`
 3. Make your changes
 4. Check and fix code style and formatting issues: `make lint`
-5. Run checks: `make test`
-6. Build the project: `make build`
+5. Run tests: `make test`
+6. Run final checks: `make check`
 7. Commit your changes using the conventions below
 8. Push your branch to your fork
 9. Open a pull request
@@ -29,10 +29,13 @@ We follow [Conventional Commits](https://www.conventionalcommits.org/) for clear
 
 ## Pull Request Guidelines
 
-1. Update documentation if needed
-2. Ensure all tests pass
-3. Address any feedback from code reviews
-4. Once approved, your PR will be merged
+1. Adhere to the coding and style guidelines of the project
+2. Perform a self-review of your own code
+3. Comment your code, particularly in hard-to-understand areas
+4. Make corresponding changes to the documentation
+5. Ensure all tests pass
+6. Address any feedback from code reviews
+7. Once approved, your PR will be merged
 
 ## Code of Conduct & Security
 

docs/providers/cookiebot.md

@@ -8,6 +8,8 @@ Cookiebot CMP integration. The CLI does **not** install the Cookiebot tag templa
 cookiebot:
   enabled: true
   templateName: Cookiebot CMP     # must match the imported template's name
+  templates:
+    tag: ''
   cookiebotId: ''
   cdnRegion: eu                    # eu or com
   urlPassthrough: false
@@ -29,3 +31,4 @@ cookiebot:
 | `urlPassthrough` | Pass identifiers via URL parameters when consent is denied. |
 | `advertiserConsentModeEnabled` | Enable advertiser consent mode signals. |
 | `regionSettings[]` | Per-region default consent states. Leave `region` blank for the global default. |
+| `templates.tag` | Path to a custom CMP tag template file. Empty (default) looks up the manually installed template. Overrides `templateName` lookup. |

docs/providers/criteo.md

@@ -10,6 +10,9 @@ criteo:
   callerId: 123
   partnerId: 123456
   applicationId: com.foomo
+  templates:
+    eventsApiTag: ''
+    userIdentification: ''
   serverContainer:
     directory: .
     packages:
@@ -30,3 +33,5 @@ criteo:
 | `partnerId` | Criteo partner ID. |
 | `applicationId` | Application identifier (often the reversed-domain form). |
 | `serverContainer.packages` | Events to forward to Criteo. |
+| `templates.eventsApiTag` | Path to a custom Events API tag template file. Empty (default) looks up the manually installed template. |
+| `templates.userIdentification` | Path to a custom User Identification template file. Empty (default) looks up the manually installed template. |

docs/providers/emarsys.md

@@ -8,6 +8,10 @@ Emarsys server-side integration.
 emarsys:
   enabled: true
   merchantId: ''
+  templates:
+    webExtendTag: ''
+    initializationClient: ''
+    initializationTag: ''
   googleConsent:
     enabled: true
     mode: analytics_storage
@@ -26,3 +30,6 @@ emarsys:
 | `merchantId` | Emarsys merchant ID. |
 | `googleConsent.mode` | Defaults to `analytics_storage`. |
 | `serverContainer.packages` | Events to forward to Emarsys. |
+| `templates.webExtendTag` | Path to a custom web extend tag template file. Empty (default) provisions the embedded template. |
+| `templates.initializationClient` | Path to a custom initialization client template file. Empty (default) provisions the embedded template. |
+| `templates.initializationTag` | Path to a custom initialization tag template file. Empty (default) provisions the embedded template. |

docs/providers/facebook.md

@@ -10,6 +10,8 @@ facebook:
   pixelId: ''
   apiAccessToken: ''
   testEventToken: ''
+  templates:
+    conversionsApiTag: ''
   googleConsent:
     enabled: true
     mode: ad_storage
@@ -36,6 +38,7 @@ facebook:
 | `testEventToken` | Optional — use Meta's test events tool to verify the payload. |
 | `googleConsent.mode` | Defaults to `ad_storage`. |
 | `serverContainer.packages` | Events to send via Conversions API. |
+| `templates.conversionsApiTag` | Path to a custom Conversions API tag template file. Empty (default) looks up the manually installed template. |
 
 ## Test events
 

docs/providers/google-analytics.md

@@ -8,6 +8,9 @@ GA4 web + server-side tagging.
 googleAnalytics:
   enabled: true
   propertyId: ''                  # used by `sesamy open ga`
+  templates:
+    jsonRequestValueVariable: ''
+    gtagClient: ''
   googleConsent:
     enabled: true
     mode: analytics_storage
@@ -41,3 +44,5 @@ googleAnalytics:
 | `googleGTagJSOverride.ecommerceItems` | Normalize ecommerce items in the override. |
 | `webContainer.packages` | Events handled in the web container. |
 | `serverContainer.packages` | Events handled in the server container. |
+| `templates.jsonRequestValueVariable` | Path to a custom JSON request value variable template file. Empty (default) provisions the embedded template. |
+| `templates.gtagClient` | Path to a custom gtag client template file. Empty (default) provisions the embedded template. |

docs/providers/microsoft-ads.md

@@ -8,6 +8,8 @@ Microsoft Ads (Bing UET) server-side conversion tracking.
 microsoftAds:
   enabled: true
   tagId: ''
+  templates:
+    conversionTag: ''
   googleConsent:
     enabled: true
     mode: ad_storage
@@ -30,6 +32,7 @@ microsoftAds:
 | `googleConsent.mode` | Defaults to `ad_storage`. |
 | `conversion.serverContainer.settings.<event>` | List of `{ conversionLabel }` pairs — one tag per entry. |
 | `conversion.serverContainer.packages` | Events to wire conversion tags for. |
+| `templates.conversionTag` | Path to a custom conversion tag template file. Empty (default) provisions the embedded template. |
 
 ::: tip
 Field names are based on the current schema. Run `sesamy config -c sesamy.yaml` to see the resolved values your build will use.

docs/providers/mixpanel.md

@@ -10,6 +10,8 @@ Track tags send UTM attribution data, so the [UTM](./utm) provider must be enabl
 mixpanel:
   enabled: true
   projectToken: ''
+  templates:
+    tag: ''
   googleConsent:
     enabled: true
     mode: analytics_storage
@@ -37,8 +39,23 @@ mixpanel:
 | Field | Purpose |
 |-------|---------|
 | `projectToken` | Mixpanel project token. |
+| `templates.tag` | Path to a custom tag template file. Empty (default) provisions the embedded template. |
 | `googleConsent.mode` | Defaults to `analytics_storage`. |
 | `serverContainer.userId` | Event-data property holding the user ID, forwarded to Mixpanel. |
 | `serverContainer.track.packages` | Events to forward to Mixpanel's `/track` endpoint. |
 
-The `Mixpanel` tag template is provisioned by the CLI — no manual template install required.
+## Tag template
+
+By default the `Mixpanel` tag template is provisioned by the CLI — no manual template install required.
+
+Set `templates.tag` to the path of a template file to provision your own instead:
+
+```yaml
+mixpanel:
+  templates:
+    tag: ./templates/mixpanel.tpl
+```
+
+The file is uploaded verbatim as the template named `Mixpanel`, so it must be a complete GTM template
+(`___INFO___`, `___TEMPLATE_PARAMETERS___`, `___SANDBOXED_JS_FOR_SERVER___`, …). Use the
+[Mixpanel](https://github.com/stape-io/mixpanel-tag) template by stape-io as a starting point.

docs/providers/pinterest.md

@@ -10,6 +10,8 @@ pinterest:
   advertiserId: ''
   apiAccessToken: ''
   testModeEnabled: false
+  templates:
+    tag: ''
   googleConsent:
     enabled: true
     mode: analytics_storage
@@ -34,3 +36,4 @@ pinterest:
 | `testModeEnabled` | Send events with the `test` flag set — won't count toward live data. |
 | `googleConsent.mode` | Defaults to `analytics_storage`. |
 | `serverContainer.packages` | Events to send. |
+| `templates.tag` | Path to a custom conversions tag template file. Empty (default) looks up the manually installed template. |

docs/providers/tracify.md

@@ -9,6 +9,8 @@ tracify:
   enabled: true
   token: ''
   customerSiteId: ''
+  templates:
+    tag: ''
   googleConsent:
     enabled: true
     mode: analytics_storage
@@ -29,3 +31,4 @@ tracify:
 | `customerSiteId` | Tracify customer site identifier. |
 | `googleConsent.mode` | Defaults to `analytics_storage`. |
 | `serverContainer.packages` | Events to forward. |
+| `templates.tag` | Path to a custom tag template file. Empty (default) provisions the embedded template. |

docs/providers/umami.md

@@ -10,6 +10,8 @@ umami:
   domain: your-domain.com
   websiteId: ''
   endpointUrl: https://umami.your-domain.com
+  templates:
+    tag: ''
   googleConsent:
     enabled: true
     mode: analytics_storage
@@ -29,3 +31,4 @@ umami:
 | `endpointUrl` | Base URL of your Umami instance. |
 | `googleConsent.mode` | Defaults to `analytics_storage`. |
 | `serverContainer.packages` | Events to forward. |
+| `templates.tag` | Path to a custom tag template file. Empty (default) provisions the embedded template. |

docs/providers/utm.md

@@ -7,6 +7,9 @@ UTM attribution for the server container. Persists the incoming UTM parameters i
 ```yaml
 utm:
   enabled: true
+  templates:
+    attributionVariable: ''
+    cookieWriterTag: ''
   googleConsent:
     enabled: true
     mode: ad_storage
@@ -15,6 +18,8 @@ utm:
 | Field | Purpose |
 |-------|---------|
 | `googleConsent.mode` | Defaults to `ad_storage`. |
+| `templates.attributionVariable` | Path to a custom attribution variable template file. Empty (default) provisions the embedded template. |
+| `templates.cookieWriterTag` | Path to a custom cookie writer tag template file. Empty (default) provisions the embedded template. |
 
 ## What gets provisioned
 

pkg/config/cookiebot.go

@@ -15,4 +15,11 @@ type Cookiebot struct {
 	AdvertiserConsentModeEnabled bool `json:"advertiserConsentModeEnabled" yaml:"advertiserConsentModeEnabled"`
 	// Default Consent state
 	RegionSettings []CookiebotRegionSetting `json:"regionSettings" yaml:"regionSettings"`
+	// Custom tag template settings
+	Templates CookiebotTemplates `json:"templates" yaml:"templates"`
+}
+
+type CookiebotTemplates struct {
+	// Path to a custom cmp tag template file, defaults to the manually installed one
+	Tag string `json:"tag" yaml:"tag"`
 }

pkg/config/criteo.go

@@ -13,8 +13,17 @@ type Criteo struct {
 	PartnerID string `json:"partnerId" yaml:"partnerId"`
 	// Criteo application id
 	ApplicationID string `json:"applicationId" yaml:"applicationId"`
+	// Custom tag template settings
+	Templates CriteoTemplates `json:"templates" yaml:"templates"`
 	// Google Consent settings
 	GoogleConsent GoogleConsent `json:"googleConsent" yaml:"googleConsent"`
 	// Google Tag Manager server container settings
 	ServerContainer contemplate.Config `json:"serverContainer" yaml:"serverContainer"`
 }
+
+type CriteoTemplates struct {
+	// Path to a custom events api tag template file, defaults to the manually installed one
+	EventsAPITag string `json:"eventsApiTag" yaml:"eventsApiTag"`
+	// Path to a custom user identification template file, defaults to the manually installed one
+	UserIdentification string `json:"userIdentification" yaml:"userIdentification"`
+}

pkg/config/emarsys.go

@@ -13,10 +13,21 @@ type Emarsys struct {
 	TestMode bool `json:"testMode" yaml:"testMode"`
 	// Enable debug mode
 	DebugMode bool `json:"debugMode" yaml:"debugMode"`
+	// Custom tag template settings
+	Templates EmarsysTemplates `json:"templates" yaml:"templates"`
 	// Google Consent settings
 	GoogleConsent GoogleConsent `json:"googleConsent" yaml:"googleConsent"`
 	// Google Tag Manager web container settings
 	WebContainer contemplate.Config `json:"webContainer" yaml:"webContainer"`
 	// Google Tag Manager server container settings
 	ServerContainer contemplate.Config `json:"serverContainer" yaml:"serverContainer"`
 }
+
+type EmarsysTemplates struct {
+	// Path to a custom web extend tag template file, defaults to the embedded one
+	WebExtendTag string `json:"webExtendTag" yaml:"webExtendTag"`
+	// Path to a custom initialization client template file, defaults to the embedded one
+	InitializationClient string `json:"initializationClient" yaml:"initializationClient"`
+	// Path to a custom initialization tag template file, defaults to the embedded one
+	InitializationTag string `json:"initializationTag" yaml:"initializationTag"`
+}