Skip to main content

Blueshift integration

Send BlueConic Experiences form responses to Blueshift as events, route visitors by Blueshift profile, and add SMS text-to-join.

The Blueshift integration in BlueConic Experiences sends form responses from your experiences to Blueshift as named events. Use these events to trigger Blueshift campaigns and journeys as soon as a visitor signs up.

Use it when you collect leads or answers in an experience and want Blueshift to act on them. The integration can also route visitors by their Blueshift subscription status, and let mobile visitors opt in to SMS with a text.


Before you begin

To set up the Blueshift integration in BlueConic Experiences, you need:

  • Blueshift enabled for your BlueConic Experiences account. The Blueshift tile appears under Attributes > Integrations once it's enabled. If you don't see the tile, contact your BlueConic account team.

  • Your Blueshift User API Key and Event API Key. In Blueshift, find them under Account settings > API keys. For more information, see API Keys.

  • Your Blueshift region: US or EU.

  • The event names you want Blueshift to receive, such as sign_up.

  • A plan for which attributes to send. For more information, see Attributes overview.

API keys must be entered by someone with access to the Blueshift account.


How does the Blueshift integration send data?

The Blueshift integration in BlueConic Experiences sends data in four linked parts:

  1. On each screen of your experience, a form field is tied to an attribute in Map Attributes.

  2. A Blueshift integration instance holds your Blueshift credentials and maps attributes to Blueshift fields.

  3. Each mapping carries a static value named event. Its value becomes the event name in Blueshift. Mappings that share an event name are sent together as one event.

  4. Instances belong to the brand, not to a single experience. Every active instance applies to every experience unless you exclude that experience on the instance.

Because instances apply brand-wide, a new experience needs no extra linking. It sends to every active Blueshift instance as soon as its fields are mapped.

BlueConic Experiences only sends events. Blueshift decides what to do with each event, including which channel a campaign uses.


Create a Blueshift integration instance

A Blueshift integration instance in BlueConic Experiences stores the credentials and settings for one Blueshift account and region. Create it once and use it for every experience in your brand.

  1. In BlueConic Experiences, go to Attributes > Integrations and open the Blueshift tile. The Instances dialog lists any existing instances.

  2. Click + Add New Instance.

  3. Enter an Integration Name that identifies the instance, for example by region or purpose.

  4. Under Credentials, enter the User API Key and the Event API Key from your Blueshift account. Both are required. The optional Email Validation Key is used only by the Email deliverable split condition and isn't part of a normal setup.

  5. Under Data Handling, turn on Active. A new instance starts with Active off and sends nothing until you turn it on.

  6. Under Region, choose US or EU to match your Blueshift account. The API endpoint follows the region.

  7. Under Excluded experiences from this integration, leave the list empty to apply the instance to every experience. To stop specific experiences from sending to this instance, select them.

  8. Add your mappings. The steps are in the mapping section of this article.

  9. Click Save. The message "We have connected to Blueshift successfully!" confirms that the instance was saved.

To add more instances, edit one, or turn one off, see Manage multiple integration instances.

Choose Data Handling settings

Two Data Handling toggles on a Blueshift integration instance control whether BlueConic Experiences sends data to Blueshift:

  • Active: turn on to send data. When it's off, the instance sends nothing. New instances start with Active off.

  • Send in preview: turn on to also send data from the normal experience preview. The Test API Integration panel sends test events whether this toggle is on or off.

The Include UIDs and Require opt-in toggles don't change what a Blueshift instance sends. A visitor identifier is sent with every Blueshift event either way.

To let Blueshift act on consent, send your opt-in checkbox value with the event. Map the attribute the checkbox is tied to, with the same event value as the other fields on that screen. The event is sent whether the box is checked or not.


Map attributes and name your Blueshift events

Mappings on a Blueshift integration instance decide which attributes BlueConic Experiences sends, under which Blueshift field names, and in which events. Give each mapping a static event value, which sets the event name Blueshift receives.

  1. On the Blueshift instance, expand Mappings and click Add mapping. The mapping form opens.

  2. Search for and pick the Attribute, for example email, first_name, or last_name.

  3. Set the Mapping name. This is the field name in Blueshift.

  4. In the same form, open Set data type, default & static values.

  5. Click Add static value. Enter the key event and, as the value, the Blueshift event name, for example sign_up. If your User API Key can load your Blueshift events, choose the event from the dropdown.

  6. Click Add mapping. The new row shows a tag such as event: sign_up.

  7. Repeat these steps for each attribute you want to send, then click Save on the instance.

Note: A mapping without an event value isn't sent to Blueshift. Check that every row shows an event: tag.

To change a mapping later, click the pencil icon (Edit) on its row, make your changes, and click Done. Then click Save on the instance.

When does each Blueshift event fire?

BlueConic Experiences sends a Blueshift event once for each screen that has at least one mapping for that event name. One experience can send several events as the visitor moves through it.

For example, an experience collects three kinds of data across two screens:

Screen

Attribute

Blueshift field

Event

1

city

city

fill_form

2

first_name, last_name

firstname, lastname

identify

2

email

email

sign_up

Screen 1 sends fill_form with the visitor's city. Screen 2 sends identify with the name fields and sign_up with the email. In Blueshift, you can use sign_up to trigger a campaign.

Avoid duplicate Blueshift campaign sends

If a Blueshift campaign is triggered by an event, put all fields mapped to that event on a single screen in your experience. When one event's fields are spread across several screens, the event is sent from each of those screens.

Each later send also includes the values collected earlier in the session for that event. Each send can trigger the campaign again, which causes duplicate sends.


Map form fields on your experience screens

For a Blueshift mapping to send a value, the form field on the experience screen must be tied to that attribute in Map Attributes. Open Map Attributes in the editor for each screen that collects data you want to send.

You don't need to link the experience to the Blueshift instance. Every active instance applies automatically unless the experience is in its Excluded experiences from this integration list.


Example: build a sign-up form that sends to Blueshift

This example creates a single-screen sign-up form in BlueConic Experiences that sends its fields to Blueshift. A single-screen form is enough to send events.

  1. In the Experience Library, click Start a New Experience, then Standard.

  2. Enter a name, choose Landing Page / Lead Form as the type, and click Create.

  3. On the screen picker, open Forms, select Simple Lead Capture, and click Add.

  4. Open Map Attributes in the editor. The template already maps First Name, Last Name, Email, and Phone Number.

  5. The template's marketing opt-in checkbox isn't mapped. Map it if you want to send it to Blueshift.

  6. Test the form with the steps in the testing section of this article.


Test the Blueshift integration before publishing

The Test API Integration panel in BlueConic Experiences shows every Blueshift event before you publish. It uses the triage tool described in Test API integrations with the triage tool.

  1. Open the experience and go to the Preview tab.

  2. Click the Test API Integration icon at the top right.

  3. Choose your Blueshift instance from the dropdown. You can search by instance name.

  4. Click through your experience and fill in the form.

  5. Check the panel. It updates about every 2 seconds and lists each screen with a mapping as its event is sent. Each event shows its screen, HTTP status, and a Sent badge. Expand an event to see its payload.

  6. In Blueshift, go to Customer Data > Profiles and search for your test email. The Activity tab shows the events.

If an event fails, use the error message in the panel. For common errors, see the troubleshooting section of Test API integrations with the triage tool.

What does a Blueshift event contain?

Each event that BlueConic Experiences sends to Blueshift contains:

  • The event name from the mapping's event value.

  • The mapped fields, under their Blueshift field names.

  • A visitor identifier, so Blueshift can link the event to a profile.

  • The experience and screen the event came from.

  • Technical details about the visit, such as IP address and browser user agent.

  • A marker that shows the event came from BlueConic Experiences.


How Blueshift links events to a visitor's profile

BlueConic Experiences sends a visitor identifier with every Blueshift event. It also sends the email address or phone number once your experience collects them. Blueshift uses these values to associate events with a profile.

The visitor identifier is your website's Blueshift cookie when two things are true. Blueshift's own site tag is on the page, and the experience uses the embed code copied from BlueConic Experiences. Otherwise, the identifier is the visitor's BlueConic Experiences ID.

You don't need to turn anything on. Once a Blueshift instance is Active, the embed code reads the Blueshift cookie from the page and passes it into the experience.

For example, an event from a question screen carries the identifier and the answer. When the visitor then submits their email, that event carries the email and the same identifier. Blueshift can then associate both events with the email profile.

BlueConic Experiences doesn't merge Blueshift profiles itself. How Blueshift resolves and merges profiles is controlled in Blueshift.


Route visitors by their Blueshift profile

A Blueshift Profile traffic split in BlueConic Experiences sends visitors down different paths based on their Blueshift subscription status. For example, a visitor who already subscribes to email can skip the email capture screen.

The Blueshift Profile split is available in a brand with an active Blueshift instance. If you don't see it, contact your BlueConic account team. For traffic splits in general, see Traffic split overview.

Each branch checks one of these conditions, set to is true or is false:

  • Known in Blueshift: the visitor has a Blueshift profile.

  • Subscribed to email: the visitor is subscribed to email in Blueshift.

  • Subscribed to SMS: the visitor is subscribed to SMS in Blueshift. Leave Sender ID blank to match a subscription from any sender. Enter a sender ID to match only subscriptions for that exact sender.

  • Email deliverable: true when Blueshift's email validation reports the visitor's address as deliverable, and false when it reports it as undeliverable. This condition needs two things: email validation turned on by your BlueConic account team, and an Email Validation Key saved on the instance. The key alone doesn't turn validation on.

Create a Blueshift Profile split

  1. In the Builder Map, open the ... menu on the screen after which the split should happen, and select Split Traffic. You can also click the line between that screen and the next one and select Split Traffic. The split is inserted between the two screens.

  2. Scroll the list of split types and choose Blueshift Profile ("Route visitors by their Blueshift subscription status").

  3. Set Branch A: choose a condition, such as Subscribed to email, and set it to is true or is false. To add more conditions, click Add Branch.

  4. Click Create. The split appears as a node on the map. Both branches first lead to the next screen.

  5. Click a branch line, choose Reconnect to new screen, then click the target screen. Repeat for the other branch.

  6. To change the condition later, click the split node, change it, and click Update.

The ... menu shows Split Traffic only when the screen already has a following screen. To start a split at the end of a path, click the + open node there and select Split Traffic. The split is added at the open end, and you connect each branch to a new screen.

Note: The position of a branch line on the map doesn't show which branch it is. Before you reconnect a branch, use Rename Branch on the line to confirm whether it's Branch A or the Default Branch.

How does a Blueshift Profile split decide the branch?

A Blueshift Profile split sends visitors who match the Branch A condition to Branch A. All other visitors take the Default Branch.

There is no separate condition for unknown visitors. If the lookup fails or times out, or the visitor can't be identified, the visitor matches neither is true nor is false. That visitor takes the Default Branch.

For example, Known in Blueshift set to is false doesn't catch visitors who can't be identified. Plan the Default Branch as the path for those visitors.

If no email or phone field is collected before the split, the split dialog shows: "No email or phone field is collected before this split. Visitors will be looked up by their Blueshift cookie only."

Example: let existing subscribers skip email capture

This example uses a Blueshift Profile split so that visitors who already subscribe to email skip the sign-up step. The experience has a question screen, an email capture screen, and a thank-you screen.

  1. Place the split between the question screen and the email capture screen.

  2. Set Branch A to Subscribed to email is true, and connect it to the thank-you screen.

  3. Connect the Default Branch to the email capture screen.

Existing subscribers go straight to the thank-you screen. Everyone else sees email capture, including visitors whose lookup failed.


Let mobile visitors opt in to SMS with a text

A Text to Join button in BlueConic Experiences lets mobile visitors subscribe to SMS by sending a prefilled text. When a visitor taps the button, their messaging app opens with your keyword filled in. The visitor sends the text to subscribe.

Text to Join is a button in your experience, not a Blueshift credential. It's available in a brand with an active Blueshift instance. If you don't see it, contact your BlueConic account team.

The keyword and number must already exist in your Blueshift SMS setup. BlueConic Experiences doesn't configure them in Blueshift.

  1. In the screen editor, add a Text to Join button.

  2. In Send to number, enter your SMS number in E.164 format, such as +15551234567, or a short code.

  3. In Message to send, enter the keyword, for example JOIN.

  4. Under On desktop, choose what desktop visitors see: Show "Text KEYWORD to NUMBER", Show a QR code, or Hide the button.

  5. Optionally, add confirmation text.

Each tap is recorded as the attribute sms_opt_in_clicked. To send taps to Blueshift, map sms_opt_in_clicked on your Blueshift instance with an event value, like any other attribute.


What to check after setup

  • The instance has Active turned on.

  • Every mapping shows an event: tag with the event name your Blueshift campaign expects.

  • All fields for a campaign-triggering event are on one screen.

  • A test submission shows each event as Sent in the Test API Integration panel.

  • The test profile in Blueshift shows the events on its Activity tab.

  • Experiences that shouldn't send to Blueshift are listed under Excluded experiences from this integration.


FAQs

Does the success message mean my Blueshift API keys work?

No. Saving doesn't check your keys with Blueshift, so "We have connected to Blueshift successfully!" appears even with a wrong key. Saving only checks that both key fields are filled in. If one is empty, you see "User API Key is required" or "Event API Key is required".

  • Wrong User API Key: the mapping form shows no error. The event value stays a plain text field instead of a dropdown of your Blueshift events.

  • Wrong Event API Key: the Test API Integration panel shows "Blueshift event API responded 401" (or 403), followed by Blueshift's own response text.

Why is my Blueshift mapping missing after I saved?

  • The mapping was filled in but never added with Add mapping. When you save with a filled-in mapping, the Unsaved mapping dialog opens. Add mapping & save keeps the mapping, Discard & save drops it, and Go back returns you to the form.

Can I send Blueshift events to both a US and an EU account?

  • Yes. Each Blueshift integration instance connects to one region, so add a separate instance for each Blueshift account and region. For more information, see Manage multiple integration instances.

How do I pause the Blueshift integration without deleting it?

  • Turn off Active under Data Handling on the Blueshift instance, then click Save. The instance stays in the Instances list with a Disabled status, and you can turn it back on at any time.

Do test submissions count in my experience reporting?

Did this answer your question?