# Enabling Tracking Stats

Highlight and Share can be used to track stats for the social networks you interact with.

### Overview

When a user shares content (via a social button or Web Share), the plugin can send a **share event** to your analytics stack. Stats are **on by default**; you can turn them off globally or restrict which data is sent for privacy.

**Three channels** receive the same event (when stats are enabled):

| Channel         | Purpose                                                              |
| --------------- | -------------------------------------------------------------------- |
| **dataLayer**   | Google Tag Manager (and any GTM-based tags).                         |
| **gtag**        | Google Analytics 4 when `gtag()` is present on the page.             |
| **CustomEvent** | Custom listeners (e.g. `window.addEventListener('has:share', ...)`). |

If stats are disabled, nothing is pushed to any channel.

***

### Event name

| Context                 | Event name                                   |
| ----------------------- | -------------------------------------------- |
| dataLayer / CustomEvent | `has:share`                                  |
| GA4 (gtag)              | `has:share` (same; GA4 params are separate). |

***

### Data sent (payload)

The event carries a small payload. **By default**, URL, share text, and title are **not** sent (they are sent as empty strings). Enable **enhanced** mode to include them.

#### dataLayer & CustomEvent (camelCase)

| Field               | When populated | Description                                                 |
| ------------------- | -------------- | ----------------------------------------------------------- |
| `event`             | Always         | Event name, e.g. `has:share`.                               |
| `hasShareType`      | Always         | Type of share, e.g. `text`, `image`.                        |
| `hasSocialNetwork`  | Always         | Network or method, e.g. `twitter`, `pinterest`, `webshare`. |
| `hasShareText`      | Enhanced only  | Selected or shared text (privacy-sensitive).                |
| `hasSharePostUrl`   | Enhanced only  | URL being shared (privacy-sensitive).                       |
| `hasSharePostTitle` | Enhanced only  | Title of the content (privacy-sensitive).                   |

#### GA4 (gtag) — snake\_case parameters

| Parameter              | When populated | Description                  |
| ---------------------- | -------------- | ---------------------------- |
| `has_share_type`       | Always         | Same as `hasShareType`.      |
| `has_social_network`   | Always         | Same as `hasSocialNetwork`.  |
| `has_share_text`       | Enhanced only  | Same as `hasShareText`.      |
| `has_share_post_url`   | Enhanced only  | Same as `hasSharePostUrl`.   |
| `has_share_post_title` | Enhanced only  | Same as `hasSharePostTitle`. |

***

### Synthetic events (CustomEvent)

The plugin dispatches a **synthetic** `CustomEvent` on `window` so your own scripts (or GTM custom HTML tags) can react to shares without relying on dataLayer or gtag.

#### What is sent

The event is dispatched as:

* **Event type:** `has:share`
* **Target:** `window`
* **Options:** `{ bubbles: true, cancelable: false }`
* **Payload:** The same payload as dataLayer is in **`event.detail`** (camelCase). When enhanced is off, `hasShareText`, `hasSharePostUrl`, and `hasSharePostTitle` are empty strings.

| Property                         | Type   | Description                                 |
| -------------------------------- | ------ | ------------------------------------------- |
| `event.detail.event`             | string | Event name (`has:share`).                   |
| `event.detail.hasShareType`      | string | Share type, e.g. `text`, `image`.           |
| `event.detail.hasSocialNetwork`  | string | Network/method, e.g. `twitter`, `webshare`. |
| `event.detail.hasShareText`      | string | Share text (empty unless enhanced).         |
| `event.detail.hasSharePostUrl`   | string | Shared URL (empty unless enhanced).         |
| `event.detail.hasSharePostTitle` | string | Content title (empty unless enhanced).      |

#### How to listen

Attach a listener to `window` for the event type `has:share`. Read the payload from `event.detail`.

```javascript
window.addEventListener( 'has:share', function( event ) {
    var payload = event.detail;
    console.log( 'Share:', payload.hasSocialNetwork, payload.hasShareType );
    // Optional: send to your own analytics or API.
} );
```

```javascript
// With enhanced enabled, you can use URL, text, and title.
window.addEventListener( 'has:share', function( event ) {
    var payload = event.detail;
    if ( payload.hasSharePostUrl ) {
        console.log( 'Shared URL:', payload.hasSharePostUrl );
    }
} );
```

The listener runs only when stats are enabled (`has_stats_enabled` / `HAS_STATS_ENABLED`). If stats are disabled, no CustomEvent is dispatched.

***

### Constants

Define these in `wp-config.php` (or before the plugin runs) to set defaults. Filters can still override them.

#### `HAS_STATS_ENABLED`

* **Default:** Stats are enabled (no constant = tracking on).
* **Use:** Set to `false` to turn off **all** stats (dataLayer, gtag, and CustomEvent).

```php
// In wp-config.php: disable all share tracking.
define( 'HAS_STATS_ENABLED', false );
```

#### `HAS_STATS_ENHANCED`

* **Default:** Enhanced data is **off** (no constant = URL, text, and title are not sent).
* **Use:** Set to `true` to allow sending URL, share text, and title in the payload.

```php
// In wp-config.php: allow sending URL, share text, and title.
define( 'HAS_STATS_ENHANCED', true );
```

***

### Filters

Use these in your theme or plugin to override the constants or implement conditional logic.

#### `has_stats_enabled`

* **Purpose:** Turn stats on or off for the frontend.
* **Default passed:** Value from `HAS_STATS_ENABLED` if defined, otherwise `true`.
* **Return:** `true` to enable, `false` to disable.

```php
// Disable all stats (e.g. for EU unless consent given).
add_filter( 'has_stats_enabled', function( $enabled ) {
    return false; // or your consent check.
} );

// Or use the helper.
add_filter( 'has_stats_enabled', '__return_false' );
```

```php
// Enable only when a consent cookie is set.
add_filter( 'has_stats_enabled', function( $enabled ) {
    return isset( $_COOKIE['analytics_consent'] ) && $_COOKIE['analytics_consent'] === 'yes';
} );
```

#### `has_stats_enhanced`

* **Purpose:** Allow or disallow sending URL, share text, and title (privacy-sensitive fields).
* **Default passed:** Value from `HAS_STATS_ENHANCED` if defined, otherwise `false`.
* **Return:** `true` to send enhanced fields, `false` to send empty strings for them.

```php
// Enable enhanced data (URL, text, title) when stats are on.
add_filter( 'has_stats_enhanced', '__return_true' );
```

```php
// Enable enhanced only for logged-in admins (example).
add_filter( 'has_stats_enhanced', function( $enhanced ) {
    return current_user_can( 'manage_options' );
} );
```


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.dlxplugins.com/highlight-and-share/developers/enabling-tracking-stats.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.