Download the PHP package stellarwp/telemetry without Composer

Telemetry Library

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

Table of Contents

• Telemetry Library
  • Table of Contents
  • Installation
  • Usage Prerequisites
  • Filters \& Actions
  • Integration
  • Uninstall Hook
  • Opt-In Modal Usage
    • Prompting Users on a Settings Page
  • Saving Opt-In Status on a Settings Page
  • How to Migrate Users Who Have Already Opted In
  • Utilizing a Shared Telemetry Instance
  • Adding Plugin Data to Site Health
  • Capturing User Events
  • Contribution

    Installation

It's recommended that you install Telemetry as a project dependency via Composer:

We actually recommend that this library gets included in your project using Strauss.

Luckily, adding Strauss to your composer.json is only slightly more complicated than adding a typical dependency, so checkout our strauss docs.

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.

In order to keep this library as light as possible, a container is not included in the library itself, however we do recommend 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, just like you have done with this library.

Filters & Actions

If you'd like to take a look at the existing filters & actions available through the library, view that documentation here.

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.

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:

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:

When a user deletes the plugin, WordPress runs the method from Uninstall and cleans up the options table. The last plugin utilizing the library will remove all options.

Opt-In Modal Usage

Prompting Users on a Settings Page

On each settings page you'd like to prompt the user to opt-in, add a do_action(). Be sure to include your defined stellar_slug.

Or, if you're implementing the library prior to version 3.0.0:

The library calls this action to handle registering the required resources needed to render the modal. It will only display the modal for users who haven't yet opted in.

To show the modal on a settings page, add the do_action() to the top of your rendered page content:

_Note: When adding the do_action, you may pass additional arguments to the library with an array. There is no functionality at the moment, but we expect to expand the library to accept configuration through the passed array._

Saving Opt-In Status on a Settings Page

When implementing the library, settings should be available for site administrators to change their opt-in status at any time. The value passed to set_status() should be a boolean.

How to Migrate Users Who Have Already Opted In

If you have a system that users have already opted in to and you'd prefer not to have them opt in again, here's how you might go about it. The opt_in() method will set their opt-in status to true and send their telemetry data and user data to the telemetry server.

Utilizing a Shared Telemetry Instance

There are cases where a plugin may want to use a shared instance of the library.

The best example of this would be an add-on plugin connecting and using the Telemetry instance of its parent plugin.

In this case, all that the plugin needs to do to implement the parent Telemetry instance is use Config::add_stellar_slug().

Adding Plugin Data to Site Health

We collect the Site Health data as json on the server. In order to pass additional plugin specific items that can be reported on, you will need to add a section to the Site Health Data. The process for adding a section is documented on developer.wordpress.org.

We do have some requirements so that we can grab the correct data from Site Health. When setting the key to the plugins site health section, use the plugin slug. Do not nest your settings in a single line, use one line per option. Do not translate the debug value. This will help make sure that the data is reportable on the Telemetry Server.

Capturing User Events

When a user completes an action, an event can be captured with the telemetry server for a specific site. These events take name and data (array) parameters to capture any specific information necessary for the event.

Some examples of actions you may want to capture:

• User creates their first post
• A plugin feature is used for the first time (but not completed or utilized)
• X days have passed and a feature has not yet been utilized

NOTE: All plugins should trigger an event when a user opts out of telemetry for a site.

To create an event, set up a do_action with the necessary details wherever you'd like to capture it:

Here is how you might log events when a user creates a new post:

Contribution

There are more detailed docs that provide guidance on contributing to the library:

• Automated testing
• Local Environment Configuration
• Quality Assurance