altis/analytics-integration-segment

Segment integration for Altis Analytics module

0.2.0 2022-04-14 23:00 UTC

Requires (Dev)

• humanmade/coding-standards: ^1.1
• phpunit/phpunit: ^9
• spatie/phpunit-snapshot-assertions: ^4.2

GPL-2.0-or-later

• Human Made Limited

README

Segment integration for Altis Analytics adds automatic exporting of analytics events to Segment via background cronjobs.

Getting Set Up

Installing

The package is automatically bundled with Altis Analytics module, however the Segment API key needs to be defined via the SEGMENT_API_WRITE_KEY constant or the altis.analytic.segment.api_write_key filter.

Usage

The package sets up a cronjob that handles batch uploading events to Segment APIs through hooking to the event altis.analytics.export.data.process that is triggered by Altis Analytics.

Functions

register_segment_group_field( string $field, array $traits = [] ) : void

Registers a grouping field, which is sent to Segment as a group call. See Segment docs on Group cals for more information.

• *$field is the event field to group by.
• *$traits is the data map to add to the group from.

register_segment_group_map( 'endpoint.Attributes.AudienceId', [ 'country' => 'endpoint.Attributes.UserAttributes.country' ] )

Actions

altis.analytics.segment.request_failure : Requests_Exception|Requests_Response $response, Array $batch

Triggered when a batch request to Segment APIs fails.

altis.analytics.segment.request_success : Requests_Response $response, Array $batch

Triggered when a batch request to Segment APIs succeeds.

altis.analytics.segment.after_send : Array<Requests_Exception|Requests_Response> $results, Array $batches, Array<Array> $events

Triggered after sending the batch request to Segment APIs.

Filters

altis.analytics.segment.api_write_key : String

Filters the Segment API key, for instances where different keys are needed for different sites. Use the constant SEGMENT_API_WRITE_KEY otherwise.

altis.analytics.segment.mapping : Array

Filters the mapping tree which the transformer uses to translate the Altis Analytics event format to the format needed by Segment. Use only if you need to customize the event structure that will be logged by Segment. The filter accepts a second parameter $type <string> that indicates the event type, eg: identify, track, group, etc.

altis.analytics.segment.formatted_data : Array

Filters the formatted data, in case further customizations are needed.

altis.analytics.segment.groups : Array

Filters the group definitions, for advanced use only, use the function register_segment_group_map() instead for simple usage.

Data mapping

The package uses a data mapping structure to convert between Altis Analytics and Segment respective formats.

Examples:

$mapping = [
    // Default format:
    'key' => 'path.to.value',

    // Basic value map:
    'country' => 'endpoint.Location.Country',

    // Use a transformative callback:
    'country' => 'endpoint.Location.Country|ucfirst',

    // Skip a specific key:
    'country' => '',

    // Merge a whole map branch (notice the absence of a key):
    'endpoint.Attributes.UserAttributes',
]