Merge pull request #25 from pantheon-systems/EI-93-analytics-and-othe…

…r-updates

[EI-93] analytics docs (and other updates)

docs/introduction.md → docs/README.md

@@ -46,7 +46,11 @@ Interests can be tested or verified in two different ways.
 
 - Use the `get_interest` function. You can return the Interest(s) from the `HeaderData` class, which can be used with the `WP_Query` class to fetch personalized content for a given visitor.
 
-### Code Samples
+### More Resources
+
+- [API](https://github.com/pantheon-systems/edge-integrations-wordpress-sdk/blob/master/docs/api.md)
+
+- [Analytics](https://github.com/pantheon-systems/edge-integrations-wordpress-sdk/blob/main/docs/analytics.md)
 
 - [Geolocation](https://github.com/pantheon-systems/edge-integrations-wordpress-sdk/blob/main/docs/geo.md)
 

docs/analytics.md

@@ -0,0 +1,59 @@
+# WordPress Edge Integrations: Analytics
+
+## Function reference
+
+### `get_gtm_code()`
+
+Returns the Google Tag Manager (GTM) code for the current site, if one is set.
+
+#### Return
+
+__(bool|string)__ The GTM code for the current site, if one is set. Otherwise, returns `false` (the default). Can also be `true` if the filter is being used to override the GTM support built into the plugin. See [`pantheon.ei.gtm_code`](#pantheoneigtm_code).
+
+#### Example
+
+```php
+$gtm_code = get_gtm_code();
+
+// Bail early if we don't have a GTM code or if the GTM code is being overridden externally.
+if ( is_bool( $gtm_code ) ) {
+	return;
+}
+?>
+<!-- Google Tag Manager (noscript) -->
+<noscript><iframe src="https://www.googletagmanager.com/ns.html?id=<?php echo esc_attr( $gtm_code ); ?>"
+height="0" width="0" style="display:none;visibility:hidden"></iframe></noscript>
+<!-- End Google Tag Manager (noscript) -->
+<?php
+```
+
+## Filter reference
+
+### `pantheon.ei.gtm_code`
+
+Allows the GTM code to be overridden. 
+
+There are three possible values for the filter: `false`, `true` or a string. 
+
+* `false` is the default, and assumes that no GTM code is set. 
+* `true` is used to override the option in the WordPress admin General Settings page. If `true` is passed, no GTM codes will be output. This is useful for sites that do not want to use GTM or are using an external plugin to add the GTM codes.
+* A string can be passed to the filter to define the GTM code. If a string is passed, the option will not appear in the WordPress admin General Settings page.
+
+#### Parameters
+
+__(bool|string)__ The GTM code for the current site.
+
+#### Examples
+Adding a GTM code via the filter:
+```php
+add_filter( 'pantheon.ei.gtm_code', 'override_gtm_code' );
+
+function override_gtm_code( $gtm_code ) {
+	return 'GTM-XXXXXXXX';
+}
+```
+
+Disabling the GTM code via the filter:
+```php
+add_filter( 'pantheon.ei.gtm_code', '__return_true' );
+```

docs/api.md

@@ -0,0 +1,118 @@
+# WordPress Edge Integrations: API
+
+## Constant reference
+
+### `PANTHEON_EDGE_INTEGRATIONS_DIR`
+
+The path to the Pantheon Edge Integrations plugin.
+
+### `PANTHEON_EDGE_INTEGRATIONS_FILE`
+
+The path to the Pantheon Edge Integrations main plugin file.
+
+### `PANTHEON_EDGE_INTEGRATIONS_VERSION`
+
+The current version of the Pantheon Edge Integrations plugin.
+
+## Function reference
+
+### `get_supported_vary_headers`
+
+Gets an array of the vary headers supported by the plugin. Before returning the array of vary headers, the [`pantheon.ei.supported_vary_headers`](#pantheoneisupportedvaryheaders) filter is applied. Only the headers (the _keys_ of `pantheon.ei.supported_vary_headers`) are returned.
+
+#### Return
+
+__(array)__ An array of the vary headers supported by the plugin.
+
+## Action reference
+
+### `pantheon.ei.after_enqueue_script`
+
+Fires immediately after the `pantheon-ei` script is enqueued.
+
+#### Parameters
+
+`$args` _(array)_ An arguments array containing `plugin_version` (the `PANTHEON_EDGE_INTEGRATIONS_VERSION` value) and `plugin_file` (the `PANTHEON_EDGE_INTEGRATIONS_FILE` value).
+
+#### Example
+
+```php
+add_action( 'pantheon.ei.after_enqueue_script', 'after_enqueue_script' );
+function after_enqueue_script( array $args ) {
+	$plugin_version = $args['plugin_version'];
+	$plugin_file    = $args['plugin_file'];
+
+	wp_localize_script( 'pantheon-ei', 'myLocalizedObj', [
+		'plugin_version' => $plugin_version,
+		'plugin_file'    => $plugin_file,
+	] );
+}
+```
+
+## Filter reference
+
+### `pantheon.ei.supported_vary_headers`
+
+Allows developers to modify the list of vary headers that are supported by the plugin.
+
+Array keys are the vary headers, and the values are whether or not they are supported.
+
+#### Parameters
+
+__(array)__ An array of vary headers and whether or not they are supported. The default values are below:
+
+```php
+$vary_headers = [
+	'Audience-Set' => true,
+	'Audience' => false,
+	'Interest' => true,
+];
+```
+
+#### Example
+To set rich Geolocation data as the only supported personalization type:
+
+```php
+add_filter( 'pantheon.ei.supported_vary_headers', 'filter_vary_headers' );
+function filter_vary_headers( array $vary_headers ) {
+	$vary_headers['Audience'] = false;
+	$vary_headers['Interest'] = false;
+
+	return $vary_headers;
+}
+```
+
+To use the country-based Geolocation data as the only supported personalization type:
+
+```php
+add_filter( 'pantheon.ei.supported_vary_headers', 'filter_vary_headers' );
+function filter_vary_headers( array $vary_headers ) {
+	$vary_headers['Audience-Set'] = false;
+	$vary_headers['Interest'] = false;
+	$vary_headers['Audience'] = true;
+
+	return $vary_headers;
+}
+```
+
+To set the vary headers to not be sent until consent has been granted (see also [Pantheon Edge Integrations Consent Management](https://github.com/pantheon-systems/pantheon-edge-integrations-consent-management)):
+
+```php
+function check_consent() {
+	if ( ! function_exists( 'wp_has_consent' ) ) {
+		return;
+	}
+
+	if ( ! wp_has_consent() ) {
+		add_filter( 'pantheon.ei.supported_vary_headers', 'do_not_send_vary_headers' );
+	}
+}
+
+function do_not_send_vary_headers() : array {
+	return [
+		'Audience-Set' => false,
+		'Audience' => false,
+		'Interest' => false,
+	];
+}
+```