Skip to content

🐸 Rybbit - open-source and privacy-friendly alternative to Google Analytics that is 10x more intuitive.

Add TYPO3 integration guide (#934)

Alexander Hofbauer684567a8040c
diff --git a/docs/content/docs/guides/typo3.mdx b/docs/content/docs/guides/typo3.mdx
new file mode 100644
index 000000000..328206430
--- /dev/null
+++ b/docs/content/docs/guides/typo3.mdx
@@ -0,0 +1,103 @@
+---
+title: TYPO3
+description: Integrate Rybbit Analytics with your TYPO3 sitepackage
+---
+
+import { Steps, Step } from 'fumadocs-ui/components/steps';
+
+Integrating Rybbit Analytics with your TYPO3 website is straightforward. You'll
+typically add the Rybbit tracking script to your main sitepackage
+`setup.typoscript` file.
+
+<Steps>
+<Step>
+### Get Your Tracking script
+
+First, you'll need your Rybbit tracking script. You can find this in your Rybbit
+dashboard under **Site Settings > Tracking Code**. It will look something like this:
+
+```html
+<script defer src="https://app.rybbit.io/api/script.js" data-site-id="YOUR_SITE_ID"></script>
+```
+
+For TYPO3 we will need pieces of this, not the full script.
+</Step>
+
+<Step>
+### Locate your main TypoScript config file
+
+In a standard TYPO3 sitepackage you'll have a main TypoScript setup file. This
+file is mostly located at: `<sitepackage>/Configuration/TypoScript/setup.typoscript`.
+
+In theory this file could be somewhere else or in a TypoScript record in the
+TYPO3 backend.
+</Step>
+
+<Step>
+### Add the Tracking Script to the `setup.typoscript` file
+
+In TYPO3 we normally don't have direct code access to the HTML `<head>`, but
+have to add those entries to the `page` object:
+
+```
+page = PAGE
+page {
+ # ...
+ includeJS {
+ rybbit = https://app.rybbit.io/api/script.js
+ rybbit.defer = 1
+ rybbit.data.data-site-id = YOUR_SITE_ID
+ }
+ # ...
+}
+```
+
+This creates a new `<script>` tag, loads the rybbit script and adds the Site ID
+data attribute.
+
+Most likely you will already have the line `page = PAGE` somewhere in your
+codebase, this also identifies the file, that is most likely to be your main
+TypoScript setup file.
+
+If you want to load the script only for your production environment, you need
+to add a condition for the `applicationContext`:
+
+```
+[applicationContext == "Production"]
+page {
+ includeJS {
+ rybbit = https://app.rybbit.io/api/script.js
+ rybbit.defer = 1
+ rybbit.data.data-site-id = YOUR_SITE_ID
+ }
+}
+[END]
+```
+
+</Step>
+
+<Step>
+### Configure values as constants
+
+It's best practice to store your Rybbit Site ID and instance URL in your site
+constants. You might have a `constants.typoscript` file in your codebase, which
+you'll use when you want to add the values to the Git repository.
+
+You can also add the values into a TypoScript record in the TYPO3 backend.
+</Step>
+
+<Step>
+### Verify Integration
+
+- Deploy your TYPO3 sitepackage to your production environment or setup
+ `applicationContext` accordingly.
+- Open your live website in a browser.
+- Navigate through a few pages.
+- Check your Rybbit dashboard for incoming data. It might take a few minutes
+ for the first events to appear.
+</Step>
+
+</Steps>
+
+That's it! Rybbit Analytics is now integrated with your TYPO3 sitepackage and
+will only track visits in your production environment.