# Friendbuy Web Mode (Actions) Destination ## Destination Info * Accepts [Page](/docs/segment/connections/spec/page), [Alias](/docs/segment/connections/spec/alias), [Group](/docs/segment/connections/spec/group), [Identify](/docs/segment/connections/spec/identify), [Track](/docs/segment/connections/spec/track) calls. * Refer to it as **Friendbuy (Actions)**, **Friendbuy (Web Destinations)**, **Friendbuy (Web Destination)** in the [Integrations object.](/docs/segment/guides/filtering-data/#filtering-with-the-integrations-object) * This destination is not compatible with [Destination Insert Functions.](/docs/segment/connections/functions/insert-functions/) * This integration is **partner owned.** Please reach out to the partner's support for any issues. [Friendbuy](https://www.friendbuy.com/) is a referral marketing platform. Friendbuy's web mode Segment integration allows you to enable your Friendbuy referral program through Segment's dashboard instead of adding Friendbuy's JavaScript directly to your site. This Segment integration is a web mode [destination action](/docs/segment/connections/destinations/actions/) 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 for use in your referral program. > \[!WARNING] > > The Friendbuy JavaScript won't be loaded unless at least one Mapping is enabled. Even if you're not sending data to Friendbuy through Analytics.js calls, if you're using Segment to load the Friendbuy JavaScript you must define and enable at least one Mapping. A safe mapping to enable is the pre-built **Track Page** mapping. ## Overview The Friendbuy web mode destination sends information about your customers and their actions to Friendbuy. It supports the following [Friendbuy tracking events](https://developers.friendbuy.com/#tracking-events). * **Track Customer**: Converts Segment [`analytics.identify`](/docs/segment/connections/spec/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')`](/docs/segment/connections/spec/ecommerce/v2/#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')`](/docs/segment/connections/spec/b2b-saas/#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`](/docs/segment/connections/sources/catalog/libraries/website/javascript/#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`](/docs/segment/connections/sources/catalog/libraries/website/javascript/#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 Web Mode (Actions) vs Friendbuy Classic 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 > \[!NOTE] > > Please contact your Friendbuy Customer Success Manager or email [support@friendbuy.com](mailto:support@friendbuy.com) to set up Friendbuy's Segment integration. Before you start, you must have Segment's Analytics.js 2.0 installed on your site. See [Segment's documentation](/docs/segment/connections/sources/catalog/libraries/website/javascript/quickstart/) for instructions. 1. Find your Friendbuy Merchant ID, a unique [UUID](https://en.wikipedia.org/wiki/Universally_unique_identifier) that Friendbuy uses to identify your account. [Log in to your Friendbuy account](https://retailer.friendbuy.io/) 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](/docs/segment/connections/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. As noted above, the Friendbuy JavaScript will not be loaded unless at least one Mapping is enabled. ## Destination Settings | Field | Description | Required | Type | | --------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------ | | Friendbuy Merchant ID | Find your Friendbuy Merchant ID by logging in to your \[Friendbuy account]\(https://retailer.friendbuy.io/) and going to Developer Center > Friendbuy Code. | Yes | string | ## Available Presets Friendbuy (Web Destination) has the following presets | Preset Name | Trigger | Default Action | | -------------- | ------------------------------- | -------------- | | Track Sign Up | Event event = "Signed Up" | Track Sign Up | | Track Customer | Event type = "identify" | Track Customer | | Track Page | Event type = "page" | Track Page | | Track Purchase | Event event = "Order Completed" | Track Purchase | ## Available Actions Build your own Mappings. Combine supported [triggers](/docs/segment/connections/destinations/actions/#components-of-a-destination-action) with the following Friendbuy (Web Destination)-supported actions: > \[!NOTE] > > Individual destination instances have support a maximum of 50 mappings. * [Track Custom Event](#track-custom-event) * [Track Sign Up](#track-sign-up) * [Track Purchase](#track-purchase-2) * [Track Customer](#track-customer) * [Track Page](#track-page-1) ### Track Custom Event Record when a customer completes any custom event that you define. Track Custom Event is a **Web** action. | Field | Description | Required | Type | | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------ | | Event Type | The type of the event to track. | Yes | STRING | | Event Properties | Object containing the properties for the event being tracked. All of the fields in this object will be sent in the root of the Friendbuy track event. | Yes | OBJECT | | Event ID | An identifier for the event being tracked to prevent the same event from being rewarded more than once. | No | STRING | | Customer ID | The user's customer ID. | Yes | STRING | | Anonymous ID | The user's anonymous id | No | STRING | | Email | The user's email address. | No | STRING | ### Track Sign Up Record when a customer signs up for a service. Track Sign Up is a **Web** action. The default Trigger is `event = "Signed Up"` | Field | Description | Required | Type | | ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------- | | Customer ID | The user's customer ID. | Yes | STRING | | Anonymous ID | The user's anonymous ID. | No | STRING | | Email | The user's email address. | Yes | STRING | | New Customer Flag | Flag to indicate whether the user is a new customer. | No | BOOLEAN | | Loyalty Program Status | The status of the user in your loyalty program. Valid values are "in", "out", or "blocked". | No | STRING | | First Name | The user's given name. | No | STRING | | Last Name | The user's surname. | No | STRING | | Name | The user's full name. | No | STRING | | Age | The user's age. | No | NUMBER | | Birthday | The user's birthday in the format "YYYY-MM-DD", or "0000-MM-DD" to omit the year. | No | STRING | | Coupon Code | Coupon code that customer supplied when they signed up. | No | STRING | | Friendbuy Attribution ID | Friendbuy attribution ID that associates the customer who is signing up with the advocate who referred them. | No | STRING | | Friendbuy Referral ID | Friendbuy referral code that associates the customer who is signing up with the advocate who referred them. | No | STRING | | Custom Attributes | Custom attributes to send to Friendbuy. You should pass an object whose keys are the names of the custom attributes and whose values are strings. Non-string-valued attributes will be dropped. | No | OBJECT | ### Track Purchase Record when a customer makes a purchase. Track Purchase is a **Web** action. The default Trigger is `event = "Order Completed"` | Field | Description | Required | Type | | ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------- | | Order ID | The order ID. | Yes | STRING | | Purchase Amount | Purchase amount to be considered when evaluating reward rules. | Yes | NUMBER | | Currency | The currency of the purchase amount. | Yes | STRING | | Coupon | The coupon code of any coupon redeemed with the order. | No | STRING | | Friendbuy Attribution ID | Friendbuy attribution ID that associates the purchase with the advocate who referred the purchaser. | No | STRING | | Friendbuy Referral ID | Friendbuy referral code that associates the purchase with the advocate who referred the purchaser. | No | STRING | | Gift Card Codes | An array of gift card codes applied to the order. | No | STRING | | Products | Products purchased. | No | OBJECT | | Customer ID | The user's customer ID. | No | STRING | | Anonymous ID | The user's anonymous ID. | No | STRING | | Email | The user's email address. | No | STRING | | New Customer Flag | Flag to indicate whether the user is a new customer. | No | BOOLEAN | | Loyalty Program Status | The status of the user in your loyalty program. Valid values are "in", "out", or "blocked". | No | STRING | | First Name | The user's given name. | No | STRING | | Last Name | The user's surname. | No | STRING | | Name | The user's full name. | No | STRING | | Age | The user's age. | No | NUMBER | | Birthday | The user's birthday in the format "YYYY-MM-DD", or "0000-MM-DD" to omit the year. | No | STRING | | Custom Attributes | Custom attributes to send to Friendbuy. You should pass an object whose keys are the names of the custom attributes and whose values are strings. Non-string-valued attributes will be dropped. | No | OBJECT | ### Track Customer Create a new customer profile or update an existing customer profile. Track Customer is a **Web** action. The default Trigger is `type = "identify"` | Field | Description | Required | Type | | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------- | ------- | | Customer ID | The user's customer ID. | Yes | STRING | | Anonymous ID | The user's anonymous id. | No | STRING | | Email | The user's email address. | Yes | STRING | | First Name | The user's given name. | No | STRING | | Last Name | The user's surname. | No | STRING | | Name | The user's full name. If the name trait doesn't exist then it will be automatically derived from the firstName and lastName traits if they are defined. | No | STRING | | Age | The user's age. | No | NUMBER | | Birthday | The user's birthday in the format "YYYY-MM-DD", or "0000-MM-DD" to omit the year. | No | STRING | | Language | The user's language. | No | STRING | | Country | The user's country. | No | STRING | | State | The user's state. | No | STRING | | City | The user's city. | No | STRING | | State | The user's postal code. | No | STRING | | Customer Since | The date the user became a customer. | No | STRING | | Loyalty Status | The status of the user in your loyalty program. Valid values are "in", "out", or "blocked". | No | STRING | | New Customer Flag | Flag to indicate whether the user is a new customer. | No | BOOLEAN | | Custom Attributes | Custom attributes to send to Friendbuy. You should pass an object whose keys are the names of the custom attributes and whose values are strings. Non-string-valued attributes will be dropped. | No | OBJECT | ### Track Page Record when a customer visits a new page. Allow Friendbuy widget targeting by Page Name instead of URL. Track Page is a **Web** action. The default Trigger is `type = "page"` | Field | Description | Required | Type | | ------------- | ------------------ | -------- | ------ | | Page Name | The page name. | No | STRING | | Page Category | The page category. | No | STRING | | Page Title | The page title. | No | STRING | ## 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: ```javascript 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 track purchase call](https://developers.friendbuy.com/#purchase-event) will be: ```javascript friendbuyAPI.push(["track", "purchase", { id: "82f250a3-32eb-40be-95fc-77e685ed8448", amount: 54.82, currency: "USD", orderNumber: "3", promotion: "black friday" }, true]); ``` Note that 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](#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 Type* 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 Type* 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](#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](https://developers.friendbuy.com/#custom-event). 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).