Gravity Forms - Blueshift Add-on

A lightweight WordPress plugin that integrates Gravity Forms with Blueshift's marketing automation platform, allowing seamless customer data synchronization and event tracking.

Description

This add-on automatically sends Gravity Forms submissions to Blueshift, creating or updating customer profiles and triggering custom events. Perfect for building email lists, tracking user signups, and automating marketing workflows.

Features

• Automatic Customer Sync: Sends form submissions to Blueshift API to create or update customer profiles
• Field Mapping: Flexible field mapper to connect Gravity Forms fields with Blueshift customer attributes
• Custom Events: Trigger custom Blueshift events on form submission (e.g., welcome emails)
• Segment Management: Assign customers to specific segments based on form submissions
• Custom API Keys: Support for different API keys per custom post type (e.g., resorts)
• Opt-in/Opt-out: Built-in confirmation field handling to respect user preferences
• Entry Notes: Automatically adds notes to Gravity Forms entries with submission status
• Error Logging: Comprehensive error logging for debugging API issues

Requirements

• WordPress: 5.0 or higher
• Gravity Forms: 2.0 or higher
• PHP: 7.0 or higher
• Blueshift Account: Active Blueshift account with API credentials

Installation

Via WordPress Admin

1. Download the plugin zip file
2. Navigate to Plugins > Add New in WordPress admin
3. Click Upload Plugin and select the zip file
4. Click Install Now and then Activate

Manual Installation

1. Download and extract the plugin files
2. Upload the blueshift-gf-addon folder to /wp-content/plugins/
3. Navigate to Plugins in WordPress admin
4. Activate Gravity Forms - Blueshift Add-on

Development Installation

# Clone or download the repository
cd wp-content/plugins/blueshift-gf-addon

# Install Node dependencies
npm install

# Build the plugin for deployment
npm run deploy

Configuration

Plugin Settings

1. Navigate to Forms > Settings > Blueshift Add-on
2. Configure the following settings:

API Key

• Field: API Key
• Description: Your Blueshift API key for customer synchronization
• Required: Yes

Event API Key

• Field: Event API Key
• Description: Your Blueshift API key for event tracking
• Required: Yes

Segment

• Field: Segment
• Description: Default segment to assign customers (can be overridden per form)
• Note: You can specify a different segment using the "segment" key in the field mapper

Custom Event

• Field: Custom Event
• Default: welcome_email
• Description: Default event to trigger on form submission
• Note: You can specify a different event using the "event" key in the field mapper

Form Settings

1. Edit any Gravity Form
2. Navigate to Settings > Blueshift Add-on
3. Configure the field mapper:

Field Mapper

Map Gravity Forms fields to Blueshift customer attributes:

Pre-defined Fields:

• firstname - First Name
• lastname - Last Name
• birth_dayofmonth - Birth Date (day)
• birth_month - Birth Month

Custom Fields: Enable "Allow Custom" to map any Blueshift field:

• segment - Override default segment
• event - Override default event
• confirmation - Opt-in/opt-out field
• Any custom Blueshift attribute

Special Behaviors:

• Email Field: Automatically detected and mapped to customer_id and email
• Birth Month: Automatically converts month names to numbers (January = 1, February = 2, etc.)

Usage

Basic Form Setup

1. Create a Gravity Form with at least an email field
2. Go to Settings > Blueshift Add-on
3. Map form fields to Blueshift attributes
4. Save settings

When a user submits the form, the plugin will:

1. Extract mapped field values
2. Add automatic fields (signup date, source, URL, etc.)
3. Send customer data to Blueshift API
4. Trigger the configured event
5. Add a note to the Gravity Forms entry

Automatic Fields

The following fields are automatically added to each submission:

Advanced: Custom API Keys per Post Type

For sites with custom post types (e.g., resort websites), you can set different API keys per post:

1. Add an Advanced Custom Field (ACF) with the key bs_api_key to your custom post type
2. Set the API key value for each post
3. The plugin will automatically use the post-specific API key instead of the global setting

Opt-in/Opt-out Handling

To respect user preferences:

1. Add a checkbox field for email confirmation (e.g., "Yes, send me updates")
2. Map this field to the key confirmation in the field mapper
3. If the field is empty (unchecked), the submission will not be sent to Blueshift
4. A note will be added to the entry: "User opted out of confirmation email"

Field Mapping Examples

Example 1: Basic Contact Form

First Name     → firstname
Last Name      → lastname
Email          → (automatically mapped)

Example 2: Newsletter Signup with Custom Segment

Email          → (automatically mapped)
Custom Value   → segment (value: "newsletter_subscribers")
Custom Value   → event (value: "newsletter_signup")

Example 3: Birthday Club

First Name     → firstname
Last Name      → lastname
Email          → (automatically mapped)
Birth Day      → birth_dayofmonth
Birth Month    → birth_month
Opt-in         → confirmation
Custom Value   → segment (value: "birthday_club")
Custom Value   → event (value: "birthday_club_signup")

API Integration

Blueshift Customer API

Endpoint: https://api.getblueshift.com/api/v1/customers

Method: POST

Authentication: Basic Auth (API Key)

Headers:

Content-Type: application/json
Authorization: Basic [base64_encoded_api_key]

Blueshift Event API

Endpoint: https://api.getblueshift.com/api/v1/event

Method: POST

Authentication: Basic Auth (Event API Key)

Headers:

Accept: application/json
Content-Type: application/json

Development

Build System

The plugin includes a Node.js build script for creating deployment packages:

# Install dependencies
npm install

# Create a versioned zip file in bundled/[version]/
npm run deploy

The build script:

• Creates a zip file with the plugin name and version
• Includes only necessary files (PHP, CSS, JS, readme.txt)
• Excludes development files (node_modules, .git, etc.)
• Outputs to bundled/[version]/[plugin-name].zip

Files Included in Build

• blueshift-addon.php - Main plugin file
• class-gfblueshiftaddon.php - Add-on class
• css/ - Stylesheets
• js/ - JavaScript files
• readme.txt - WordPress plugin readme (if exists)

Debugging

The plugin uses WordPress error logging. To view logs:

1. Enable WordPress debugging in wp-config.php:

   define('WP_DEBUG', true);
   define('WP_DEBUG_LOG', true);
   define('WP_DEBUG_DISPLAY', false);

2. Check wp-content/debug.log for entries like:

   • API Key usage (global vs. custom)
   • Mapped fields being sent
   • API responses
   • Error messages

Hooks and Filters

The plugin uses the Gravity Forms Add-on Framework. Key hooks:

• gform_after_submission - Processes form data after submission
• Standard GF Add-on Framework methods for settings and field mapping

Troubleshooting

Submissions Not Sending to Blueshift

Check:

1. API keys are configured correctly in Forms > Settings > Blueshift Add-on
2. Form has at least one email field
3. Email field is not empty
4. If using confirmation field, make sure it's checked
5. Check debug.log for error messages

Common Error Messages

Entry Notes

Check Gravity Forms entry notes for status:

• ✅ "Successfully sent submission to Blueshift"
• ✅ "Successfully sent [event] event to user"
• ⚠️ "API Key is empty. Not sending to Blueshift"
• ⚠️ "User opted out of confirmation email"
• ⚠️ "Email is required to update or create customer"

Changelog

Version 3.2.1

• Current stable release
• Full Blueshift integration
• Custom field mapping support
• Event API integration

Version 3.1.3

• Initial public release

License

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

License: GPL-2.0-or-later

Credits

Author: Braudy Pedrosa

Based on: Gravity Forms Add-On Framework

Copyright: 2012-2016 Rocketgenius Inc.

Support

For issues, questions, or feature requests, please contact the plugin author or refer to your Blueshift account manager for API-related questions.

Resources

• Gravity Forms Documentation
• Gravity Forms Add-On Framework
• Blueshift API Documentation
• WordPress Plugin Development