{"id":28746879,"url":"https://github.com/geanramos/ga4_tracker","last_synced_at":"2025-06-16T15:49:14.289Z","repository":{"id":298068992,"uuid":"998759776","full_name":"geanramos/ga4_tracker","owner":"geanramos","description":"GA4 Tracker for YOURLS","archived":false,"fork":false,"pushed_at":"2025-06-09T08:16:42.000Z","size":0,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-06-09T08:42:50.238Z","etag":null,"topics":["awesome","awesome-list","bitly","php","plugin","shortener","url-shortener","yourls","yourls-api","yourls-extension","yourls-plugin"],"latest_commit_sha":null,"homepage":"http://dev.geanramos.com.br/ga4_tracker/","language":"PHP","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/geanramos.png","metadata":{"files":{"readme":"README-EN.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-06-09T07:52:37.000Z","updated_at":"2025-06-09T08:25:59.000Z","dependencies_parsed_at":"2025-06-09T08:42:53.944Z","dependency_job_id":"d4029b2e-81e2-467e-8947-e9848e4425fe","html_url":"https://github.com/geanramos/ga4_tracker","commit_stats":null,"previous_names":["geanramos/ga4_tracker"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/geanramos/ga4_tracker","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/geanramos%2Fga4_tracker","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/geanramos%2Fga4_tracker/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/geanramos%2Fga4_tracker/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/geanramos%2Fga4_tracker/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/geanramos","download_url":"https://codeload.github.com/geanramos/ga4_tracker/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/geanramos%2Fga4_tracker/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":260192312,"owners_count":22972595,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["awesome","awesome-list","bitly","php","plugin","shortener","url-shortener","yourls","yourls-api","yourls-extension","yourls-plugin"],"created_at":"2025-06-16T15:48:53.040Z","updated_at":"2025-06-16T15:49:14.268Z","avatar_url":"https://github.com/geanramos.png","language":"PHP","funding_links":[],"categories":[],"sub_categories":[],"readme":"# GA4 Tracker for YOURLS\n\nThis plugin integrates your YOURLS installation with Google Analytics 4 (GA4), allowing you to track every click on your shortened links as a custom event. Communication is handled securely and efficiently using Google's Measurement Protocol v2, without impacting the user's redirection speed.\n\n**Plugin Version:** 1.0\n\n**YOURLS Compatibility:** 1.7.x or higher\n\n**Author:** [Gean Ramos](https://geanramos.com.br)\n\n---\n\n## Table of Contents\n\n- [What Does This Plugin Do?](#what-does-this-plugin-do)\n- [Why Use This Plugin?](#why-use-this-plugin)\n- [How It Works](#how-it-works)\n- [Installation and Configuration](#installation-and-configuration)\n- [Verifying It Works](#verifying-it-works)\n- [UTM Parameter Compatibility](#utm-parameter-compatibility)\n- [Contributing](#contributing)\n- [License](#license)\n\n## What Does This Plugin Do?\n\n* **Native GA4 Integration:** Sends data directly to your Google Analytics 4 property.\n* **Event Tracking:** Each click on a shortened link is recorded as a custom event named `yourls_redirect`.\n* **Uses the Measurement Protocol:** It uses the official and recommended method by Google for sending server-side data, ensuring speed and reliability.\n* **Simple Configuration Panel:** Adds an easy-to-use admin page for you to securely enter your GA4 credentials.\n\n## Why Use This Plugin?\n\n1.  **Maximum Speed:** Unlike JavaScript-based methods, tracking via the Measurement Protocol happens on the server. This means your user's redirection experiences **no delay**.\n2.  **Superior Reliability:** Server-to-server communication is more robust and is not affected by ad-blockers or the user's browser privacy settings, ensuring more accurate data collection.\n3.  **Detailed Data for Analysis:** Having a dedicated `yourls_redirect` event allows you to create specific reports, funnels, and segments in GA4 to analyze the performance of your shortened links, which isn't possible with standard pageview tracking.\n4.  **Security and Best Practices:** Your credentials (API Secret) are stored securely in the YOURLS database, and communication with Google is done via HTTPS.\n\n## How It Works\n\nThe plugin uses a modern and efficient approach to tracking:\n\n1.  **Redirection Hook:** The plugin uses the `pre_redirect` hook from YOURLS, which is a function triggered seconds before a link is redirected.\n2.  **Data Collection:** At this moment, the plugin collects essential information: the destination long URL, the keyword (short URL), and anonymous user data, such as the IP address and User-Agent (browser information).\n3.  **`client_id` Creation:** GA4 requires a `client_id` to identify a \"user.\" The plugin creates a pseudo-anonymous identifier by combining and hashing (with SHA1) the IP and User-Agent, respecting privacy.\n4.  **Sending via Measurement Protocol:** With all the data ready, the plugin builds a JSON request and sends it to Google Analytics' servers in the background, without waiting for a response, ensuring the user is redirected instantly.\n\n## Installation and Configuration\n\nFollow these steps to get the plugin running in minutes.\n\n### 1. Plugin Installation\n\n1.  Create a folder named `ga4-tracker` inside the `/user/plugins/` directory of your YOURLS installation.\n2.  Create a file named `plugin.php` inside the `ga4-tracker` folder.\n3.  Copy and paste the [plugin code](https://raw.githubusercontent.com/geanramos/ga4_tracker/refs/heads/main/plugin.php) into the `plugin.php` file you created.\n4.  Go to your YOURLS admin page, click on **Manage Plugins**, and activate the **\"GA4 Tracker\"** plugin.\n\n### 2. Configuration in Google Analytics 4\n\nFor the plugin to work, you need a **Measurement ID** and an **API Secret**.\n\n1.  **Get the Measurement ID:**\n    * Go to your GA4 property.\n    * Navigate to **Admin** \u003e **Data Streams**.\n    * Click on your web data stream. Your Measurement ID (e.g., `G-XXXXXXXXXX`) will be visible. Copy it.\n\n2.  **Create the API Secret:**\n    * On the same \"Data Streams\" screen, click on **Measurement Protocol API secrets**.\n    * Click **Create**, give it a nickname (e.g., `YOURLS Plugin`), and click **Create** again.\n    * **Copy the \"Secret value\" immediately.** It will not be shown again.\n\nFor more details, refer to the [official Google documentation](https://developers.google.com/analytics/devguides/collection/protocol/v2/getting-started).\n\n### 3. Plugin Configuration in YOURLS\n\n1.  After activating the plugin, a new link named **\"GA4 Tracker Settings\"** will appear in the admin menu.\n2.  Click on it, enter the **Measurement ID** and **API Secret** you obtained, and click **\"Save Settings\"**.\n\n## Verifying It Works\n\nThe best way to verify that events are being sent is by using the **DebugView** in GA4:\n\n1.  Click on one of your shortened links to generate an event.\n2.  In GA4, go to **Admin** \u003e **DebugView**.\n3.  Within a few seconds, you should see the `yourls_redirect` event appear on the timeline, confirming that the integration is working.\n\n## UTM Parameter Compatibility\n\nThis plugin is **100% compatible** with URLs containing UTM parameters (`utm_source`, `utm_medium`, etc.) and actually enhances tracking.\n\n| Step | Action | Result |\n| :--- | :--- | :--- |\n| **1. Click** | User clicks `sho.rt/promo23`. | The process begins. |\n| **2. Plugin** | Our plugin sends the `yourls_redirect` event to GA4 with the long URL and its UTMs. | You get real-time click data. |\n| **3. YOURLS** | Redirects the user's browser to the long URL with UTMs. | The user reaches the correct destination. |\n| **4. GA4** | The script on your destination site reads the UTMs from the URL and attributes the session to your campaign. | Your Traffic Acquisition reports are correct. |\n\nYou get the best of both worlds: standard GA4 campaign tracking working perfectly and a custom event to analyze clicks specifically.\n\n## Contributing\n\nContributions are welcome! Feel free to open an *issue* to report bugs or suggest improvements, or submit a *pull request* with your changes.\n\n## License\n\nThis plugin is distributed under the [MIT License](https://github.com/geanramos/ga4_tracker/blob/main/LICENSE).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgeanramos%2Fga4_tracker","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgeanramos%2Fga4_tracker","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgeanramos%2Fga4_tracker/lists"}