altis / experiments
Web Experimentation framework for Altis
Installs: 35 041
Dependents: 0
Suggesters: 0
Security: 0
Stars: 11
Watchers: 19
Forks: 1
Open Issues: 7
Language:JavaScript
Type:wordpress-plugin
Requires
- altis/aws-analytics: ^2.3.1
- markrogoyski/math-php: ^0.51.0
- dev-master
- 2.4.4
- 2.4.3
- 2.4.2
- 2.4.1
- 2.4.0
- 2.3.0
- 2.2.2
- 2.2.1
- 2.2.0
- 2.1.0
- 2.0.4
- 2.0.3
- 2.0.2
- 2.0.1
- 2.0.0
- 1.1.0
- 1.0.0
- dev-2.4.4--branch
- dev-2.4.3--branch
- dev-2.4.2--branch
- dev-2.4.1--branch
- dev-2.4.0--branch
- dev-2.3.0--branch
- dev-2.2.2--branch
- dev-2.2.1--branch
- dev-2.2.0--branch
- dev-v2-branch
- dev-2.1.0--branch
- dev-2.0.4--branch
- dev-updating-npm-deps
- dev-2.0.3--branch
- dev-2.0.2--branch
- dev-2.0.1--branch
- dev-2.0.0--branch
- dev-1.1.0--branch
- dev-1.0.0--branch
- dev-0.1.0--branch
This package is auto-updated.
Last update: 2024-10-24 18:17:59 UTC
README
Web Experimentation framework for Altis.
Features
The plugin currently provides the following built in features:
Post Title A/B Tests
With this feature enabled it's simple to create A/B Tests for your post titles directly from the post edit screen.
It is enabled by default but can be disabled using the following filter:
add_filter( 'altis.experiments.features.titles', '__return_false' );
Posts and pages are supported by default however you can add support for custom post types using the following code in a plugin or your theme's functions.php
:
add_post_type_support( 'events', 'altis.experiments.titles' );
Usage
The plugin provides a programmatic API to register custom A/B Tests for post data:
register_post_ab_test( string $test_id, array $options )
Sets up the test.
$test_id
: A unique ID for the test.$options
: Configuration options for the test.label <string>
: A human readable label for the test.rest_api_variants_field <string>
: The field name to make variants available at.rest_api_variants_type <string>
: The data type of the variants.goal <string>
: The conversion goal event name, eg "click" or "click:.selector a".goal_filter <string | callable>
: Elasticsearch bool query to filter goal results. If a callable is passed it receives the test ID and post ID as arguments.query_filter <string | callable>
: Elasticsearch bool query to filter total events being queried. If a callable is passed it receives the test ID and post ID as arguments.variant_callback <callable>
: An optional callback used to render variants based. Arguments:$value <mixed>
: The variant value.$post_id <int>
: The post ID.$args <array>
: Optional args passed tooutput_ab_test_html_for_post()
.
winner_callback <callable>
: An optional callback used to perform updates to the post when a winner is found. Defaults to no-op. Arguments:$post_id <int>
: The post ID$value <mixed>
: The winning variant value.
post_types <array>
: An array of supported post types for the test.
output_ab_test_html_for_post( string $test_id, int $post_id, string $default_content, array $args = [] )
Returns the A/B Test markup for client side processing.
$test_id
: A unique ID for the test.$post_id
: The post ID for the test.$default_content
: The default content for users not in the test.$args
: An optional array of data to pass through tovariant_callback
.
namespace Altis\Experiments; // Register the test. register_post_ab_test( 'featured_images', [ 'rest_api_variants_type' => 'integer', 'goal' => 'click', 'variant_callback' => function ( $attachment_id, $post_id, $args ) { return wp_get_attachment_image( $attachment_id, $args['size'], false, $args['attr'] ); } ] ); // Apply the test by filtering some standard output. add_filter( 'post_thumbnail_html', function ( $html, $post_id, $post_thumbnail_id, $size, $attr ) { return output_ab_test_html_for_post( 'featured_images', $post_id, $html, [ 'size' => $size, 'attr' => $attr, ] ); }, 10, 5 );
Goal Tracking
Conversion goals are how it is determined whether a variant has been successful or not. This is calculated as the number of conversions / number of impressions
.
The click
goal handler is provided out of the box and adds a click event handler to the nearest <a>
tag.
Scoped Event Handling
For tests where more complex alternative HTML is being rendered you can define the event target with a CSS selector passed to element.querySelectorAll()
.
For example setting the goal to click:.my-target
will track a conversion when the element in the variant HTML matching .my-target
is clicked. This applies for all registered goal handlers.
Custom Goal Handlers
You can define your own goal handlers in JavaScript:
Altis.Analytics.Experiments.registerGoal( name <string>, callback <function>, closest <array> )
This function adds a goal handler where name
corresponds to the value of $options['goal']
when registering an A/B Test.
The callback receives the following parameters:
element <HTMLElement>
: Target node for the event.record <function>
: Receives the target element and a callback to log the conversion. The function accepts two optional arguments:attributes <object>
: Custom atttributes to record with the event.metrics <object>
: Custom metrics to record with the event.
The closest
parameter allows you to ensure the element passed to your callback is of a certain type, achieved by stepping up through the DOM tree, for example to return only anchor tags you would pass [ 'a' ]
.
Altis.Analytics.Experiments.registerGoal( 'scrollIntoView', function ( element, record ) { var listener = function () { // Check element has come into view or not. if ( element.getBoundingClientRect().top > window.innerHeight ) { return; } // Remove event listener immediately. window.removeEventListener( 'scroll', listener ); // Record event. record(); }; // Start listening to scroll events. window.addEventListener( 'scroll', listener ); } );
Note: This JavaScript should be enqueued in the <head>
via the wp_enqueue_scripts
action.
Creating your own tests
How you manage the variant data is up to you, for example you could use Fieldmanager or Advanced Custom Fields to create metaboxes to save the variant data.
Note you should use the following functions to get and update the variants:
get_ab_test_variants_for_post( string $test_id, int $post_id ) : array
update_ab_test_variants_for_post( string $test_id, int $post_id, array $variants )
Roadmap
- Multivariate testing capability
- Features
- Featured image tests
Made with ❤️ by Human Made