Custom Code Guide for Website-Integrators

With any online business, marketing and analytic managers offer a variety of insights that allow businesses the ability to see how customers are interacting with their business. By analyzing information such as page clicks, time spent on the site, and conversion information, businesses are able to adjust their approach to optimize conversions and cater to their specific market.

An important part of this is analyzing conversion patterns: what items are selling, who is buying them, etc. To report this information in real time, marketing managers provide “pixels” or bits of javascript to be placed on a “thank you” page on the client’s website. This thank you page is only designed to be accessed after a conversion occurs, so when the thank you page is loaded, the conversion pixel fires, and reports relevant information about the most recent conversion.

This can be done within FareHarbor, but the process varies slightly. The entire FareHarbor booking occurs within the Lightframe, which is an iframe technically off of the client’s site. Because of this, typical thank you pages are not able to access the conversion information from the LightFrame. Instead, these pixels must be added to the booking confirmation page within the LightFrame. Custom code is FareHarbor’s feature that allows these pixels to be added and fired on the booking confirmation page within the LightFrame.

These pixels can be customized with specialized variables to report booking specific conversion information to the client’s marketing manager. When a custom code request is sent to Integrators, it is their job to inject the booking variables and add it to the dashboard so it will fire on successful conversion.

In regards to custom code, the FareHarbor product is simple and fairly customizable. All custom code is loaded into the dashboard via the Analytics and Tracking page in the dashboard’s settings. Google Analytics, Facebook, Adroll, and Optimizely all have built in dashboard functionality. For these services, we only need to add account information from the client’s marketing service, and the FareHarbor product does the rest. All other custom code pixels must be added using the Custom Code option.

When the customer reaches the booking confirmation page, an iframe is loaded into the HTML of the page. This source of the iframe is a custom booking specific link. Within this link there are two things:

1. A script that creates the booking variable. This is a JSON object that contains booking specific information such as transaction totals, booking id, item names, etc. Below is an example of what the booking variable looks like.

2. Any code added through custom code on the dashboard.

The custom code is able to detect variables from the booking object to be passed into various analytics managers at the time of booking.

<script> console.log(booking) </script>

Specifics for completing the most common requests are described later in this document, but the general method of implementation is usually the same.

1. Claim the request in Airtable
2. Copy the code provided into a code editor
3. Inject the booking variables where requested
4. Test on your demo dashboard to ensure there are no errors
5. Add to the client’s dashboard through Analytics and Tracking
6. Report as completed in #website-integrations and mark complete in Airtable.

In order to dynamically send booking information into their analytics manager, many pixels require booking variables to be injected into the code. Since these variables are properties on the booking object, you can use javascript dot notation to reference the different properties.

The booking variable has the following properties:

There are a few formats in which you can inject variables.

In Javascript

Many pixels operate by creating a javascript object with booking properties, and then sending the whole object to the analytics manager. This object will be set up with key / value pairs. Replace whatever placeholder text is present with the value from the property column above. Take the following example:

In this case, replace the “123.05” static value with booking.totalInDollars. If the client is in the US, we can leave “USD” hardcoded, but if they are in another country, we would change the value for currency to booking.currency. The updated script will look as such:

In Links and URLS

Clients may also try to load a tag that sends information through a link. To use a variable in links, it must be wrapped in double braces, like {{ booking.pk }} For the following example:

<img src="http://example.com/?sale-id=booking_id&value=booking_total />

Variables would be injected like so:

<img src="http://example.com/?sale-id={{ booking.pk }}&value={{ booking.total_in_dollars }} />

Unfortunately the FareHarbor product functionality is limited. There are many setups the client may request that are not possible. The most common limitations we see are as follows:

• We cannot track the origin of bookings made on FH.

  • Exception being Google Ads that can track a customer’s session from the original ad into the LightFrame through cookies.
  • This also may be possible through an API connection, but the submitter would have to check with the connectivity team.

• Limited amount of variables in the booking object

  • We are only able to send info based on what is available through the booking object.
  • No customer info (names, phone number etc.) can be passed through custom code.
  • View the booking object table to see what can be passed.
• The ability to add custom code is limited to FareHarbor employees.
  • This is largely for security purposes. Potentially dangerous javascript could be added to the dashboard if access was given out freely.

• Only one item can be tracked per booking.

  • For cart setups with multiple items being sold at once, the booking object will report on only the first item in the cart. There is no way to pass through an array of all items in the customer’s cart.

• Only HTML and therefore vanilla Javascript can be used in custom code section.

• No way to send tracking info through URL or cookies.
  • There is a complex custom setup that can potentially accomplish this, but should only be considered for enterprise clients. Escalate to your team lead if something like this is being requested.
• Can’t track any activity within the LightFrame until the booking confirmation page.
  • Exception being Google Analytics can track and report clicks within the LightFrame if using the built in tool on the Dashboard, but no other services can do this.
• Can’t track to a client’s Thank You page on their website.
  • FareHarbor accomplishes the same functionality through custom code, therefore all pixels must be added to the Dashboard.
  • We can redirect after booking to a Thank You page but will not accomplish anything related to tracking.
  • More info down below.
• Tag trackers and Chrome extensions will likely not be able to detect the pixel.
  • Since the booking confirmation page is within an iframe, the parent page will not register the pixel. This does not mean that the pixel is not working.
  • The pixel, however, can be seen in the elements when inspecting the confirmation page with dev tools.

Before implementing the pixel on the client’s live dash, it is important to test it on your demo dash. This will ensure that the pixel runs and does not have any glaring issues. Be aware that even if no errors are thrown, it does not mean the pixel is working how the client intends. The pixel can run while also not passing the correct information.

Setting up your demo dash

It is recommended that you do a few things before testing any pixels on your demo dash. Create an item called “FareHarbor Test Booking”, this will ensure that when booking information is passed, it is clear to the client that it was a test.

Add a customer type to your demo dash that has no cost and apply it to your Test Booking item. This will ensure that you do not need to enter any payment information when completing your test booking. Create daily availabilities for this item.

To test on your demo dash:

1. Navigate to the “analytics and tracking” menu in your demo dash.
2. After adding any necessary variables, add the pixel as a custom code block.
3. Open your test booking link in an incognito tab, apply the free Customer Type and complete the booking
4. Look in your console to ensure there are no errors. Note that “Report Only” errors are ok, this is a simulated CORS error that is not actually occurring.

If a client says that the pixel is not set up correctly or is not converting correctly, there are a few things that we can try:

1. Copy the code into a code editor before adding to the dashboard.

   • When copying directly from Airtable or an email, certain characters (particularly quotation marks) can be incorrectly replaced.

2. Look at the pixel for glaring issues.

   • Is a method being called that isn’t declared?
   • Are there any missing characters like semicolons?
   • Are the booking variables added correctly?
   • Are the booking variables mistakenly being added as strings?

3. Test on your demo dash and check for potential errors

   • Syntax errors should show up.
   • Check to make sure it’s not calling a function that isn’t declared.

4. Make sure the LightFrame is working properly on their site

   • For Google Analytics / Ads, the LightFrame is required in order to track a customer’s session from the website to the conversion pixel. If it is not working, it may incorrectly report conversion information.

5. Check the links on the website for hardcoded GA tags.

   • GA tags should be added to the URL dynamically from the gtag on the client’s site. If they are hardcoded, conversion information will pass incorrectly.

6. Compare with similar pixels we have completed before.

   • Check Airtable to see if we have seen this before?
   • Is there anything we did originally or missing from the new pixel that might be necessary?

7. Check the pixels documentation.

   • Google to see if you can find the documentation for this pixel. What pieces of code are required to make this code work? Make sure the client is not forgetting to include something.

8. Consider the order of the script.

   • If an event snippet calls a function before it has been declared, it will not execute.

9. Consider combining pixels into one custom code.

   • If a pixel and event snippet rely on each other to run, they need to be placed in the same custom code instance.

10. Have the submitter send the client the pixel exactly as it is set up on the dash. Ask them if they see any potential issues.

11. What format should the booking variables be returned?

    • If the client is expecting an integer value, and it is returning a string, it will report incorrectly.
    • booking.totalInDollars should be used for Integers, booking.total_in_dollars should be used for strings.

12. What exactly is the client expecting to see?

    • Sometimes the client can be expecting to see information reported that is not possible. Have the submitter ask the client exactly what they are expecting to see. Check and make sure that what they are expecting is not on the list of limitations above

13. Talk to your team lead, you may have to tell the client we are unable to fix their issue.

If you have made it through these steps and the client is still complaining, notify your team lead. We may have to tell them that there is nothing else we can do. It is not easy or expected that we can understand what a client’s pixel is trying to do, or how their backend is configured to interpret information. We are not marketing experts and there is only so much we can do with only the pixel they provided. If we have no documentation, have implemented it as they sent over, and checked the most common errors, there is nothing else we can do.

Sometimes a client may request that the LightFrame redirect to a certain page upon successful booking. This is technically possible though very hacky and a security risk. Usually a client is requesting this in order to send conversion codes from their thank you page. Make sure the client understands that conversion info cannot be passed from the thank you page. The client can have other scripts run on the thank you page, but since the booking happens entirely within the Lightframe, the conversion pixel must go in the dashboard. If the client understands this and still wants the redirect, notify your team lead.

Identifiers are a feature in the dashboard that lets you reuse common pieces of code. By adding a single value to the identifiers field, it can be called in your custom code by using the identifier value. This is a very underutilized feature, but it works as follows.

For multiple values, you can also set identifiers up as a json object with key / value pairs. This can be called from your custom code using dot notation.

The client already has a similar tag in the dashboard. Should I add the new pixel?

• If the pixel is completely identical, reach out to the submitter and let them know. If it is a pixel for the same service with a different ID, you can add it in addition. It is likely they are trying to report to more than one account.

The client failed to include a part of the pixel. What should I do?

• There are certain cases where we might be able to find it ourselves. If the missing piece is universal and does not have any account specific information, we can use old instances to find what needs to be added. Additionally, if the missing piece only needs an account number that we are already given, we can add it and substitute the account number. If the missing piece is completely unique, tell the submitter to request it from the client.

The client is complaining they don’t see the conversion pixel through their browser tag tracker.

• Because the conversion pixel is added to only the booking confirmation page of the LightFrame, it will not be detected by any browser tools. The browser tool only looks for tags on the parent document, where the conversion pixel does not exist. Ensure the client that the tag should still be firing as intended.