Segment Grails Plugin

Introduction

IMPORTANT: Project retirement

This project is retired. As Micronaut become core of the Grails starting at Grails 4, please, use Micronaut Segment instead.

The Segment Plugin allows you to integrate Segment in your Grails application.

Segment lets you send your analytics data to any service you want, without you having to integrate with each one individually.

It provides the following Grails artefacts:

SegmentService - A server side service client to call Segment APIs, which is a wrapper around the official Segment Analytics for Java library.
SegmentTagLib - A collection of tags to use Segment Analytics.js Library in your GSPs.

Installation

Declare the plugin dependency in the build.gradle file, as shown here:

dependencies {
    ...
    compile "org.grails.plugins:segment:2.1.1"
    ...
}

Config

Create a Segment account, in order to get your own apiKey (for client-side API calls).

Add your Segment.io site apiKey to your grails-app/conf/application.yml:

grails:
    plugin:
        segment:
            apiKey: {API_KEY} # Write key

By default, Segment integration will only be enabled for Production environments. If you need it to be enabled for other environments, make sure that it is explicitly enabled in your configs.

grails:
    plugin:
        segment:
            enabled: true

If you're using Intercom, you can automatically enable Intercom secure mode (for segment:identify) by adding you Intercom secret key:

grails:
    plugin:
        segment:
            intercomSecretKey: {INTERCOM_SECRET_KEY}

Usage

SegmentService

You can inject segmentService in any of your Grails artefacts (controllers, services...) in order to call Segment APIs.

def segmentService

// Identify and set traits
segmentService.identify('bob@bob.com', [gender: 'male'])

// Identify and set traits with past date (JodaTime DateTime representing when the identify took place)
segmentService.identify(
    'bob@bob.com',
    [gender: 'male'],
    new DateTime(2012, 3, 26, 12, 0, 0, 0)
)

// Identify and set traits with past date and context
segmentService.identify(
    'bob@bob.com', [gender: 'male'],
    new DateTime(2012, 3, 26, 12, 0, 0, 0),
    [
        integrations: [
            'All': false,
            'Mixpanel': true,
            'KISSmetrics': true
        ],
        ip: '192.168.0.10'
    ]
)

// Track an event
segmentService.track('bob@bob.com', 'Signed up')

// Track an event and set properties
segmentService.track(
    'bob@bob.com',
    'Signed up',
    [plan: 'Pro', amount: 99.95]
)

// Track a past event and set properties with past date
segmentService.track(
    'bob@bob.com', 'Signed up',
    [plan: 'Pro', amount: 99.95],
    new DateTime(2012, 3, 26, 12, 0, 0, 0)
)

// Track a past event and set properties with past date and context
segmentService.track(
    'bob@bob.com',
    'Signed up',
    [plan: 'Pro', amount: 99.95],
    new DateTime(2012, 3, 26, 12, 0, 0, 0),
    [
        integrations: [
            'All': false,
            'Mixpanel': true,
            'KISSmetrics': true
        ],
        ip: '192.168.0.10'
    ]
)

// Group
segmentService.group('bob@bob.com', 'companyId', [
    name: 'The company name',
    website: 'http://www.company.com'
])

// Record page view
segmentService.page('bob@bob.com', 'Pricing')

// Record page view with extra info
segmentService.page('bob@bob.com', 'Pricing', 'Business', [
    title: 'Segment.io Pricing',
    path: '/pricing'
])

// Record screen view
segmentService.screen('bob@bob.com', 'Register', 'Business', [
    type: 'facebook'
])

// Alias identity
segmentService.alias('bob@bob.com', 'bob')

SegmentTagLib

To use Segment Analytics.js Library, you must first initialize it in page header (most probably in you layout GSP).

JS Lib initialization

<!DOCTYPE html>
<html>
<head>
    <segment:initJS/>

Or with default page view tracking disabled:

    <segment:initJS pageTracked="false"/>

Identification and event recording

Once initialized, you can use Segment Analytics.js Library in your GSP views.

<!-- Identify current user -->
<segment:identify userId="bob@bob.com"/>

<!-- Identify current user and set traits -->
<segment:identify userId="bob@bob.com" traits="${[gender: 'male']}"/>

<!-- Identify a group and set traits -->
<segment:group groupId="power_users" traits="${[plan: 'silver']}"/>

<!-- Identify current user with context -->
<segment:identify
    userId="bob@bob.com"
    context="${[integrations: ['All': false, 'Mixpanel': true, 'KISSmetrics': true]]}"/>

<!-- Track an event -->
<segment:track event="Signed Up"/>

<!-- Track an event and set properties -->
<segment:track event="Signed Up" properties="${[plan: 'Pro', revenue: 99.95]}"/>

<!-- Track an event with context -->
<segment:track
    event="Signed Up"
    context="${[integrations: ['All': false, 'Google Analytics': true, 'Customer.io': true]]}"/>

<!-- Track a link click -->
<segment:trackLink
    event="Signed Up"
    link="\$('a.signup-link')"
    properties="${[plan: 'Pro', revenue: 99.95]}"/>

<!-- Track a form submission -->
<segment:trackForm
    event="Signed Up"
    form="\$('form.signup-form')"
    properties="${[plan: 'Pro', revenue: 99.95]}"/>

<!-- Page view -->
<segment:page category="Some category" name="Page title"/>

<!-- Page view with name -->
<segment:page name="Page title"/>

<!-- Page view with category and name -->
<segment:page category="Some category" name="Page title"/>

<!-- Alias identity -->
<segment:alias originalId="bob@bob.com" newId="bob"/>

Bugs

To report any bug, please use the project Issues section on GitHub.

agorapulse / grails-segment