PHPackages                             stellarwp/telemetry - PHPackages - PHPackages  [Skip to content](#main-content)[PHPackages](/)[Directory](/)[Categories](/categories)[Trending](/trending)[Leaderboard](/leaderboard)[Changelog](/changelog)[Analyze](/analyze)[Collections](/collections)[Log in](/login)[Sign up](/register)

1. [Directory](/)
2. /
3. [Utility & Helpers](/categories/utility)
4. /
5. stellarwp/telemetry

ActiveLibrary[Utility & Helpers](/categories/utility)

stellarwp/telemetry
===================

Telemetry library for StellarWP plugins.

2.3.4(1y ago)11972.8k↑85.7%2[8 PRs](https://github.com/stellarwp/telemetry/pulls)GPL-2.0-or-laterPHPPHP >=7.1CI passing

Since Jan 10Pushed 3mo ago18 watchersCompare

[ Source](https://github.com/stellarwp/telemetry)[ Packagist](https://packagist.org/packages/stellarwp/telemetry)[ RSS](/packages/stellarwp-telemetry/feed)WikiDiscussions develop Synced 1mo ago

READMEChangelog (10)Dependencies (10)Versions (35)Used By (0)

Telemetry Library
=================

[](#telemetry-library)

[![Tests](https://github.com/stellarwp/telemetry/actions/workflows/tests.yml/badge.svg)](https://github.com/stellarwp/telemetry/actions/workflows/tests.yml/badge.svg)[![Coding Standards](https://github.com/stellarwp/telemetry/actions/workflows/phpcs.yml/badge.svg)](https://github.com/stellarwp/telemetry/actions/workflows/phpcs.yml/badge.svg)[![PHP Compatibility](https://github.com/stellarwp/telemetry/actions/workflows/compatibility.yml/badge.svg)](https://github.com/stellarwp/telemetry/actions/workflows/compatibility.yml/badge.svg)[![Static Analysis](https://github.com/stellarwp/telemetry/actions/workflows/phpstan.yml/badge.svg)](https://github.com/stellarwp/telemetry/actions/workflows/phpstan.yml/badge.svg)

A library for Opt-in and Telemetry data to be sent to the StellarWP Telemetry server.

Table of Contents
-----------------

[](#table-of-contents)

- [Telemetry Library](#telemetry-library)
    - [Table of Contents](#table-of-contents)
    - [Installation](#installation)
    - [Usage Prerequisites](#usage-prerequisites)
    - [Filters & Actions](#filters--actions)
    - [Integration](#integration)
    - [Uninstall Hook](#uninstall-hook)
    - [Opt-In Modal Usage](#opt-in-modal-usage)
        - [Prompting Users on a Settings Page](#prompting-users-on-a-settings-page)
    - [Saving Opt-In Status on a Settings Page](#saving-opt-in-status-on-a-settings-page)
    - [How to Migrate Users Who Have Already Opted In](#how-to-migrate-users-who-have-already-opted-in)
    - [Utilizing a Shared Telemetry Instance](#utilizing-a-shared-telemetry-instance)
    - [Adding Plugin Data to Site Health](#adding-plugin-data-to-site-health)
    - [Capturing User Events](#capturing-user-events)
    - [Contribution](#contribution)

Installation
------------

[](#installation)

It's recommended that you install Telemetry as a project dependency via [Composer](https://getcomposer.org/):

```
composer require stellarwp/telemetry
```

> We *actually* recommend that this library gets included in your project using [Strauss](https://github.com/BrianHenryIE/strauss).
>
> Luckily, adding Strauss to your `composer.json` is only slightly more complicated than adding a typical dependency, so checkout our [strauss docs](https://github.com/stellarwp/global-docs/blob/main/docs/strauss-setup.md).

Usage Prerequisites
-------------------

[](#usage-prerequisites)

To actually *use* the telemetry library, you must have a Dependency Injection Container (DI Container) that is compatible with the [StellarWP Container Contract](https://github.com/stellarwp/container-contract).

In order to keep this library as light as possible, a container is not included in the library itself, however we do recommend [di52](https://github.com/lucatume/di52). To avoid version compatibility issues, it is also not included as a Composer dependency. Instead, you must include it in your project. We recommend including it via composer [using Strauss](https://github.com/stellarwp/global-docs/blob/main/docs/strauss-setup.md), just like you have done with this library.

Filters & Actions
---------------------

[](#filters--actions)

If you'd like to take a look at the existing filters & actions available through the library, [view that documentation here](docs/filters.md).

Integration
-----------

[](#integration)

Initialize the library within your main plugin file after plugins are loaded (or anywhere else you see fit). You can configure a unique prefix (we suggest you use your plugin slug) so that hooks can be uniquely called for your specific instance of the library.

```
use StellarWP\Telemetry\Core as Telemetry;

add_action( 'plugins_loaded', 'initialize_telemetry' );

function initialize_telemetry() {
	/**
	 * Configure the container.
	 *
	 * The container must be compatible with stellarwp/container-contract.
	 * See here: https://github.com/stellarwp/container-contract#usage.
	 *
	 * If you do not have a container, we recommend https://github.com/lucatume/di52
	 * and the corresponding wrapper:
	 * https://github.com/stellarwp/container-contract/blob/main/examples/di52/Container.php
	 */
	$container = new Container();
	Config::set_container( $container );

	// Set the full URL for the Telemetry Server API.
	Config::set_server_url( 'https://telemetry.example.com/api/v1' );

	// Set a unique prefix for actions & filters.
	Config::set_hook_prefix( 'my-custom-prefix' );

	// Set a unique plugin slug.
	Config::set_stellar_slug( 'my-custom-stellar-slug' );

    // Initialize the library.
    Telemetry::instance()->init( __FILE__ );
}
```

Using a custom hook prefix provides the ability to uniquely filter functionality of your plugin's specific instance of the library.

The unique plugin slug is used by the telemetry server to identify the plugin regardless of the plugin's directory structure or slug.

If you need to hook into an existing instance of the library, you can add your plugin's stellar slug with:

```
add_action( 'plugins_loaded', 'hook_into_existing_telemetry' );

function hook_into_existing_telemetry() {
	// Check to make sure that the Telemetry library is already instantiated.
	if ( ! class_exists( Telemetry::class ) ) {
		return;
	}

	// Register the current plugin with an already instantiated library.
	Config::add_stellar_slug( 'my-custom-stellar-slug', 'custom-plugin/custom-plugin.php' );
}
```

Uninstall Hook
--------------

[](#uninstall-hook)

This library provides everything necessary to uninstall itself. Depending on when your plugin uninstalls itself and cleans up the database, you can include this static method to have the library purge the options table of the necessary rows:

```