How to set up the Segment Web-Mode (Destination Actions) Integration

William Harper Updated by William Harper

Notice: This page is about support for the latest Actions-framework Segment Friendbuy Destination. There's also a page about the legacy non-Actions based Friendbuy Destination, which is in maintence mode and only supported on Friendbuy's legacy platform. Please contact your Onboarding & Implementation Representative or support@friendbuy.com if you are interested in setting up a Segment integration.

Friendbuy's Segment integration allows you to enable your Friendbuy referral program through Segment's dashboard instead of adding Friendbuy's JavaScript directly to your site.

Friendbuy’s Segment integration is implemented as a Segment browser destination action that loads and configures Friendbuy’s JavaScript for you. If you’re already using Segment’s Analytics.js to identify your customers and track their purchases, either directly or through Segment source integrations that you’ve installed, you can configure Segment to send this data to Friendbuy and use in your referral program.

Overview

The Friendbuy destination can send information about your customers and their actions to Friendbuy. It supports the following Friendbuy tracking events.

  • Track Customer. Converts Segment analytics.identify calls to Friendbuy track customer calls. Use this to add your customer ID and other customer data to the information that Friendbuy has about the customer.
  • Track Purchase. Converts Segment analytics.track('Order Completed') calls to Friendbuy track purchase calls. Use this to send purchase data to Friendbuy and reward advocates based on their friends’ purchases.
  • Track Sign-Up. Converts Segment analytics.track('Signed Up') calls to Friendbuy track sign_up calls. Use this to reward customers for account creation and other sign-up actions.
  • Track Page. Converts Segment analytics.page calls to Friendbuy track page calls. Use this to enable your Friendbuy widgets based on page name.
  • Track Custom Event. Converts an arbitrary Segment analytics.track call with an event name and properties of your choosing to a Friendbuy track custom event call. Use this to reward your customers for actions other than purchases or sign-ups.

Benefits of Friendbuy's Web Mode (Actions) vs Friendbuy's Classic (Legacy) Destinations

Friendbuy Web Mode (Actions) is the Segment web mode destination that works with Friendbuy’s current platform. The classic Segment Friendbuy destination works with Friendbuy’s legacy platform.

Getting Started

Before you start, you must have Segment’s Analytics.js 2.0 installed on your site. See Segment’s documentation for instructions.

  1. Find your Friendbuy Merchant ID, a unique UUID that Friendbuy uses to identify your account. Log in to your Friendbuy account and visit the Developer Center> Friendbuy Code page to locate your Merchant ID.
  2. From the Segment web app, click Catalog, then click Destinations.
  3. Filter the destinations on Friendbuy in the Catalog and select Friendbuy Web Device Mode (Actions). Click Configure Friendbuy Web Device Mode (Actions)to configure the Friendbuy destination, and choose which of your sources to connect the destination to.
  4. Give the destination a name, and fill in the settings manually.
  5. On the Basic Settings page enter your Merchant ID value from step one, and click Save Changes.
  6. Select the Mappings tab. A number of pre-built mappings are configured for you that map standard events defined in the Segment Spec to their equivalent Friendbuy events, as displayed below. You can disable events that you don’t use or edit the pre-built field mappings.
  7. After you configure the destination, enable it from the Settings tab.

Pre-built mappings

By default, a Friendbuy Web Mode (Actions) Destination comes with the following mappings.

MAPPING NAME

TRIGGER

FRIENDBUY ACTION

Track Customer

identify calls

Track Customer

Track Purchase

track calls with name Order Completed

Track Purchase

Track Sign Up

track calls with name Signed Up

Track Sign Up

Track Page

page calls

Track Page

Available Actions

Build your own subscriptions! Combine supported triggers with the following -supported actions:

Edit Friendbuy mappings

There are four steps to configure a Segment mapping.

  1. Set up event trigger: Choose the event trigger, which is the event type (such as Identify) or event name (such as Order Completed) for events that should be sent to Friendbuy.
  2. Test event trigger: Find a sample event in your Segment event stream that matches the trigger you defined in step one.
  3. Configure action fields: Define how the fields in the Segment event are mapped to fields in the Friendbuy track event.
  4. Review mappings: Verify that the fields in the sample event are mapped correctly.

Configuring Action Fields

In the configure action fields step, the mapping is pre-populated with mappings from the standard Segment event properties to the corresponding Friendbuy fields. You can edit each field if you want to populate that field from a different Segment event property or not send the field at all.

Note that the default mappings for the Purchase, Sign Up, and custom events populate Friendbuy’s Customer ID field from the User ID passed in the analytics.identify call. Unless you change the Customer ID field mapping when you configure the action, you must make an analytics.identify call before you make the analytics.track call for Purchase, Sign Up, or custom events if you want to associate a Customer ID with those events.

Custom Attributes

In the Track Customer, Track Purchase, or Track Sign Up mappings you can use the Custom Attributes field to send additional custom properties that aren’t included in the predefined field names for that event. Use the mapping’s Custom Attributes field to specify the path to a JSON object that contains those custom attributes. Then, when your code makes its Segment Analytics.js call, include an object at the path that you configured containing your custom attributes to include them at the root of the Friendbuy track event.

For example, if your Track Purchase call has the default Custom Attributes value of properties.friendbuyAttributes, and if your track purchase call is:

analytics.track("Order Completed", {
  order_id: "82f250a3-32eb-40be-95fc-77e685ed8448",
  total: 54.82,
  currency: "USD",
  friendbuyAttributes: {
    orderNumber: "3",
    promotion: "black friday"
  }
});

then the Friendbuy purchase track call will be:

friendbuyAPI.push(["track", "purchase", {
  id: "82f250a3-32eb-40be-95fc-77e685ed8448",
  amount: 54.82,
  currency: "USD",
  orderNumber: "3",
  promotion: "black friday"
}, true]);
Note: a Friendbuy track call is limited to a maximum of 10 custom attributes, custom attribute values must be strings, and the maximum length of a custom attribute is 128 characters. Custom attributes that do not comply with these restrictions are dropped.

Custom Events

To allow Friendbuy to act on an event that isn’t one of the standard events described in the Overview, use a custom event.

To configure a custom event:

  1. Click New Mapping and choose Track Custom Event.
  2. For the Event Name, choose the name of the Segment event you are tracking. For example, if you want to reward on app downloads that you are tracking with analytics.track("Downloaded", { downloadId: "My App" }, select Downloaded as your Event Name.
  3. When you configure your action fields, you can accept the default Event Name of event which will cause Friendbuy to receive track events with the same names as the Segment events. If you want to rename the Friendbuy events, you can replace the Event Name with a different value such as the static string download.
  4. Event Properties is set from the path properties by default, which means that all the properties that you include in your Segment analytics.track call are passed to Friendbuy. If you only want to pass custom attributes to Friendbuy, you need to segregate the fields to pass to Friendbuy into an object and then specify the path to that object, similar to what is described above in Custom Attributes.
  5. To prevent an event that is tracked multiple times from being rewarded more than once, you should include a deduplication ID in your event as described in Friendbuy’s Track Custom Event documentation. You can either pass an explicit Event ID field in your event (defaulting to the deduplicationId property) or you can create the Event ID out of other event properties (such as the userId, a ., and the properties.downloadId in the above example).

How did we do?

How to Integrate Friendbuy as a Segment Source

Contact