README

一个用于将 Opt-in 和遥测数据发送到 StellarWP 遥测服务器的库。

安装

建议您通过 Composer 将遥测作为项目依赖项安装

composer require stellarwp/telemetry

我们实际上建议您使用 Strauss 将此库包含在项目中。

幸运的是，将 Strauss 添加到您的 composer.json 并不比添加一个典型的依赖项复杂多少，所以请查看我们的 strauss 文档。

使用前提

为了实际使用遥测库，您必须有一个与 StellarWP 容器合约兼容的依赖注入容器 (DI 容器)。

为了使此库尽可能轻量，库中不包括容器，但我们推荐 di52。为了避免版本兼容性问题，它也不作为 Composer 依赖项包含。相反，您必须将其包含在项目中。我们建议您通过 composer 使用 Strauss 来包含它，就像您包含此库一样。

过滤器 & 动作

如果您想查看通过库提供的现有过滤器 & 动作，请在此处查看文档。

集成

在插件加载后（或您认为合适的任何地方）初始化库。您可以配置一个唯一的前缀（我们建议您使用您的插件 slug），以便为库的特定实例唯一调用钩子。

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__ );
}

使用自定义钩子前缀提供对插件特定实例库功能进行唯一过滤的能力。

唯一的插件 slug 由遥测服务器使用，以识别插件，无论其目录结构或 slug 如何。

如果您需要连接到库的现有实例，您可以通过

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' );
}

卸载钩子

此库提供卸载本身所需的一切。根据您的插件何时卸载并清理数据库，您可以包含此静态方法，以便库清除必要的选项表中的行

<?php// uninstall.php

use YOUR_STRAUSS_PREFIX\StellarWP\Telemetry\Uninstall;

require_once 'vendor/strauss/autoload.php';

Uninstall::run( 'my-custom-stellar-slug' );

当用户删除插件时，WordPress 会运行 Uninstall 方法并清理选项表。最后使用库的插件将删除所有选项。

Opt-In 模态框使用

在设置页面上提示用户

在您想要提示用户 Opt-in 的每个设置页面上添加 do_action()。 请确保包括您定义的 stellar_slug。

do_action( 'stellarwp/telemetry/optin', '{stellar_slug}' );

或者，如果您在版本 3.0.0 之前实现此库

/**
 * Planned Deprecation: 3.0.0
 *
 * Please use 'stellarwp/telemetry/optin' action instead.
 */
do_action( 'stellarwp/telemetry/{stellar_slug}/optin' );

库通过这个动作调用以处理渲染模态所需的资源注册。它只为尚未同意的用户显示模态。

要在设置页面上显示模态，请在渲染的页面内容顶部添加do_action()。

function my_options_page() {
    do_action( 'stellarwp/telemetry/optin', '{stellar_slug}' );
    ?>
    <div>
        <h2>My Plugin Settings Page</h2>
    </div>
    <?php
}

注意：当添加do_action时，您可以通过数组传递额外的参数给库。目前没有功能，但我们预计库将扩展以通过传递的数组接受配置。

do_action( 'stellarwp/telemetry/optin', '{stellar_slug}', [ 'plugin_slug' => 'the-events-calendar' ] );

在设置页面上保存 Opt-In 状态

在实现库时，应该为网站管理员提供设置，以便他们可以在任何时候更改他们的同意状态。传递给set_status()的值应该是一个布尔值。

add_action( 'admin_init', 'save_opt_in_setting_field' );

/**
 * Saves the "Opt In Status" setting.
 *
 * @return void
 */
public function save_opt_in_setting_field() {
	// Return early if not saving the Opt In Status field.
	if ( ! isset( $_POST[ 'opt-in-status' ] ) ) {
		return;
	}

	// Get an instance of the Status class.
	$Status = Config::get_container()->get( Status::class );

	// Get the value submitted on the settings page as a boolean.
	$value = filter_input( INPUT_POST, 'opt-in-status', FILTER_VALIDATE_BOOL );

	$Status->set_status( $value );
}

如何迁移已经 Opt-in 的用户

如果您有一个用户已经同意的系统，并且您希望他们不需要再次同意，以下是您可以这样做的方式。`opt_in()`方法将他们的同意状态设置为`true`并将他们的遥测数据和用户数据发送到遥测服务器。

/**
 * The library attempts to set the opt-in status for a site during 'admin_init'. Use the hook with a priority higher
 * than 10 to make sure you're setting the status after it initializes the option in the options table.
 */
add_action( 'admin_init', 'migrate_existing_opt_in', 11 );

function migrate_existing_opt_in() {

	if ( $user_has_opted_in_already ) {

		// Get the Opt_In_Subscriber object.
		$Opt_In_Subscriber = Config::get_container()->get( Opt_In_Subscriber::class );
		$Opt_In_Subscriber->opt_in();
	}
}

利用共享遥测实例

有些情况下，插件可能希望使用库的共享实例。

最好的例子是一个附加插件连接并使用其父插件的遥测实例。

在这种情况下，插件为了实现父遥测实例需要做的只是使用Config::add_stellar_slug()。

use STRAUSS_PREFIX\StellarWP\Telemetry\Config;

add_action( 'plugins_loaded', 'add_plugin_to_telemetry' );

function add_plugin_to_telemetry() {

	// Verify that Telemetry is available.
	if ( ! class_exists( Config::class ) ) {
        return;
    }

	// Set a unique plugin slug and include the plugin basename.
	Config::add_stellar_slug( 'my-custom-stellar-slug', 'my-custom-stellar-slug/my-custom-stellar-slug.php' );
}

将插件数据添加到站点健康

我们在服务器上以json格式收集网站健康数据。为了传递可以报告的额外插件特定项，您需要在网站健康数据中添加一个部分。添加部分的流程在developer.wordpress.org上有文档说明。

我们有一些要求，以便我们可以从网站健康中获取正确数据。当设置插件网站健康部分的键时，使用插件别名。不要将设置嵌套在一行中，每行一个选项。不要翻译调试值。这将有助于确保数据可以在遥测服务器上报告。

function add_summary_to_telemtry( $info ) {
	$info[ 'stellarwp' ] = [
			'label'       => esc_html__( 'StellarWP Plugin Section', 'text-domain' ),
			'description' => esc_html__( 'There are some key things here... Everything should be output in key value pairs. Follow the translation instructions in the codex (do not translate debug). Plugin Slug should be the main key.', 'text-domain' ),
			'fields'      => [
				'field_key_one' => [
					'label' => esc_html__( 'This is the field text', 'text-domain' ),
					'value' => esc_html__( 'value', 'text-domain' ),
					'debug' => 'value'
				],
				'field_key_two' => [
					'label' => esc_html__( 'Field Two', 'text-domain' ),
					'value' => esc_html__( 'yes', 'text-domain' ),
					'debug' => true,
				],
				'field_key_three' => [
					'label' => esc_html__( 'Three', 'text-domain' ),
					'value' => esc_html__( 'Tempus pellentesque id hac', 'text-domain' ),
					'debug' => 'Tempus pellentesque id hac',
				],
				'field_key_four' => [
					'label' => esc_html__( 'Option Four', 'text-domain' ),
					'value' => esc_html__( 'on', 'text-domain' ),
					'debug' => true,
				],
			],
		];
	return $info;
}

add_filter( 'debug_information', 'add_summary_to_telemetry', 10, 1) ;

捕获用户事件

当用户完成一个操作时，可以捕获特定站点的遥测服务器中的事件。这些事件使用name和data（数组）参数来捕获事件所需的所有特定信息。

以下是一些您可能想要捕获的操作示例

用户创建他们的第一个帖子
第一次使用插件功能（但未完成或使用）
经过X天后，一个功能尚未被使用

注意：所有插件应在用户从站点的遥测中退出的情况下触发一个事件。

要创建一个事件，设置一个带必要详细信息的do_action，在您想要捕获事件的地方。

// Event data is sent to the telemetry server as JSON.
$data = [
	'one'   => 1,
	'two'   => 2,
	'three' => 3,
];
do_action( 'stellarwp/telemetry/{hook-prefix}/event', 'your-event-name', $data );

以下是当用户创建新帖子时记录事件的示例

/**
 * Log event when a user creates a new post.
 *
 * @action save_post
 *
 * @param int     $post_id The ID of the post being saved.
 * @param WP_Post $post    The post object being saved.
 * @param bool    $update  If this is an update to a pre-existing post.
 *
 * @return void
 */
function user_creates_post( $post_id, $post, $update ) {
	// Only send events for new posts.
	if ( $update ) {
		return;
	}

	// Only send event for posts, avoid everything else.
	if ( $post->post_type !== 'post' ) {
		return;
	}

	// Add any data to the event that needs to be captured.
	$event_data = [
		'title'   => $post->post_title,
		'content' => $post->post_content,
		'some-other-data' => 'use the array to capture anything else that might be necessary for context'
	];

	// Log the event with the telemetry server.
	do_action( 'stellarwp/telemetry/{hook-prefix}/event', 'new_post', $event_data );
}

贡献

有更详细的文档提供有关如何为库做出贡献的指导

stellarwp / telemetry

维护者

详细信息