Lifecycle

Lifecycle Hooks

Evolv includes several lifecycle events that trigger throughout the execution of the runtime, such as when the runtime is initialized, when a page loads, and when an experiment is selected. Evolv exposes hooks for each of these events, and you can attach custom event handlers to these hooks.

When a lifecycle event occurs, it returns an associated LifecycleEvent, which you can use to access the event's properties. To learn more about each hook, click on the name of the hook in the Lifecycle Event column.

Name	Level	Lifecycle Event	Description
initialize	Runtime	InitializeEvent	Occurs when the Evolv script has finished loading, but before it attempts to load the runtime or experiments.
initialized	Runtime	InitializedEvent	Occurs when the runtime has finished loading.
reconciled	Runtime	ReconciledEvent	Occurs after reconciliation has completed.
skipped	Runtime	SkippedEvent	Occurs when no experiments have been declared in either the first stage in a first-impression scenario, or the first two stages in a reconciliation scenario.
stagecompleted	Stage	StageCompletedEvent	Occurs after all known, applicable experiment execution plans have been run.
filtered	Experiment	FilteredEvent	Occurs during the stage building phase when an experiment has been explicitly excluded from the execution plan, or when the user is found to not meet the audience criteria.
selected	Experiment	SelectedEvent	Occurs when the user has been selected into an experiment after meeting the experiment's audience criteria.
rendered	Experiment	RenderedEvent	Occurs after changes have been applied to all activated pages, but only if the render timeout has not been exceeded.
notrendered	Experiment	NotRenderedEvent	Occurs when an experiment changes should be applied, but the render timeout has been exceeded.
activated	Page	ActivatedEvent	Occurs when a URL meets the matching conditions of a page in an experiment, but before changes are applied.
reverted	Page	RevertedEvent	Occurs when changes from an experiment have been reverted either manually or by reconciliation.
triggered	Trigger	TriggeredEvent	Occurs after an event has been emitted.

Attaching to a Lifecycle Hook

The on method lets you register a custom handler to a lifecycle hook. This allows you to run custom JavaScript code when a event occurs in the Evolv lifecycle. The off method removes a handler from a hook. Both of these methods are available via the global evolv namespace.

Example

In this example, we have a function that creates a log message when a user is selected into an experiment. We attach it to the selected hook, which runs each time the user meets the audience conditions for an experiment. The handler logs the event to the console along with the experiment ID:

function logUserSelected(e) {
    console.log('User was selected into experiment ' + e.experimentId);
}

evolv.on('selected', logUserSelected);

The following example removes the handler that we attached in the evolv.on example. Now, when the lifecycle hook fires, the event will no longer be logged to console:

evolv.off('selected', logUserSelected);