Bluon FSM Plugin

Bring Bluon's complete data and AI environment together in a battle-tested UI that can be quickly and easily embedded into your web or mobile applications.

1. Overview

The Bluon FSM Plugin brings Bluon's complete data and AI environment together in a battle-tested UI, that can be quickly and easily embedded into your own web or mobile applications. While designed for Field Service Management software, it can be used with most custom applications that allow iframes or webviews.

2. Benefits

•

Encapsulation: The embedded web functionality is completely separate from the native application.

•

WebView Compatibility: Allows media playback and message reception from the embedded web page.

•

Easy to integrate: Can be included with just a few lines of code.

•Support for desktop, tablet, and mobile viewports.

•Basic customizations such as logo and colors to match your brand theme.

3. System Requirements

Browser Compatibility

Chrome, Firefox, and Safari.

Minimum Screen Resolution

For optimal display:

•Desktop: 1140 x 1024
•Tablet: 820 x 1180
•Mobile: 390 x 844

4. Environments

We provide two environments for implementing FSM in your application: a UAT environment for all types of testing, and a production environment. There is a base URL to which various parameters can be configured, allowing access to all the features FSM offers to users.

https://[domain]/?id=iframeId

[domain]	Environment
demo.bluon.com	UAT environment
plugin.bluon.com	PRD environment

5. URL Parameters

Parameter	Description
`id *`	Unique id for every iframe embed in the website or app
`view *`	It accepts 2 different possibilities: search: access to Search page master-mechanics: access to Master Mechanics page hvac-tools: access to the home page of our HVAC Tools
`origin *`	It accepts 2 different possibilities: web: when accessed from a web browser on a desktop computer app: when accessed through a website on a mobile device (phone or tablet) It is recommended to detect the device and set this parameter dynamically. The behavior when accessing the camera or files differs between these two approaches.
`mode *`	For FSM functionality, the value fsm must be passed.
`showTabs`	It accepts 2 different possibilities: (Default value is true) true: show the tabs section to switch between model search and part search false: hide the tabs section to switch between model search and part search
`tab`	It accepts 2 different possibilities: (Default value is models) models: initialize the search screen in the model section parts: initialize the search screen in the part section
`searchMode`	It accepts 2 different possibilities: (Default value is normal) normal: allow access to the traditional model detail asset: allow access to the special model detail for the Assets flow
`isNameplateReaderModal`	It accepts 2 different possibilities: (Default value is false) true: show the quick access screen for nameplate scanning false: show the traditional FSM search screen
`showManually`	It accepts 2 different possibilities: (Default value is false) true: show the button for manual search access on the scanning screen false: hide the button for manual search access on the scanning screen
`addAsset`	It accepts 2 different possibilities: (Default value is false) true: displays the Add Job button on the Model Detail page false: hide the Add Job button on the Model Detail page Note: this is tied to a specific flag that allows the "Add Asset" to default flows.
`updateAsset`	It accepts 2 different possibilities: (Default value is false) true: displays the Add Job button on the Model Detail page with a custom text, for example: "Update Equipment" false: displays the Add Job button on the Model Detail page with default text Note: this is tied to addAsset param.
`initSearch`	Accepts a string that will be used to perform a direct search. This parameter is directly related to the tab parameter, as the search will be conducted on models or parts depending on its value.
`modelDetail`	Accepts a model UUID to initialize the screen directly on its detail view.
`userId`	Internal identifier of the user
`companyId`	Unique identifier of the company
`companyName`	Name of the company
`companyEmail`	Contact email address of the company
`companyZipCode`	Postal code of the company's address
`companyPhone`	Contact phone number of the company

* Required parameter

These parameters provide flexibility to customize the user experience with Bluon FSM. You can see usage examples in the Summary of shortcut examples section.

6. Authentication Methods

There are two authentication methods, depending on the type of implementation. If the implementation is carried out on a website, domain-based authentication will be mandatory. On the other hand, if the implementation is done within a mobile application, authentication will be handled using a token provided by Bluon.

WEBPAGE

If the implementation is web-based, the 'device' parameter will not be required, and the iframe must be initialized by sending an initialization message. This way, the system will detect the web domain where the application is running and use it for authentication.

HTML Example:

<iframe
   src='https://[domain]/?id=iframe&...'
   onLoad={(e) => {
      const iframe = e.currentTarget;
      const message = {
         event: 'init',
      };
      setTimeout(() => {
         iframe.contentWindow?.postMessage(JSON.stringify(message), '*');
      }, 500);
   }}
/>

MOBILE APP

When the iframe is implemented from a mobile application, the 'device' parameter must be used to pass the token that enables authentication.

Request your access key directly to your Bluon account manager. Separate keys will be provided for each environment. The access key provided to your company is confidential and should not be shared with unauthorized individuals. Sharing this key may compromise security and lead to unauthorized access. We are not responsible for any issues, data breaches, or unauthorized activities resulting from misusing or sharing your company's access key.

React Native Example:

const BluonFSMWebView = () => {
  return (
    <WebView
      mediaPlaybackRequiresUserAction={false}
      allowsInlineMediaPlayback={true}
      source={{
        uri: 'https://[domain]/?id=iframe&device=[yourAccessKey]&...',
      }}
    />
  );
};

export default BluonFSMWebView;

7. Asset Event

Add Job

In the Asset flow, the iframe can emit an event to the parent when a job is completed. This event can be listened to by the parent using the name 'add-job', and as a response, it will receive a JSON object containing all the data associated with the job.

Web Example:

window.addEventListener("message", (event) => {
   if (event.origin !== "https://[domain]") return;

   try {
      const message = JSON.parse(event.data);
      if (message.event === 'add-job') {
         handleAddJob(message.data);
      }
   } catch (error) {...}
}, false);

React Native Example:

const BluonFSMWebView = () => {

   const handleEvents = (event) => {
      if (event.origin !== "https://[domain]") return;

      try {
         const message = JSON.parse(event.data);
         if (message.event === 'add-job') {
            handleAddJob(message.data);
         }
      } catch (error) {...}
   };

   return (
      <WebView
         mediaPlaybackRequiresUserAction={false}
         allowsInlineMediaPlaybook={true}
         source={{uri:'https://[domain]/?id=iframe&device=[yourAccessKey]&...',
      }}
      onMessage={handleEvents}
    />
  );
};

export default BluonFSMWebView;

Each custom implementation can store, display, or perform different actions with the received information.

Below is an example of the event response along with an explanation of each of its values.

Response Example:

{
   "event": "add-job",
   "data": {
      "scanData": {
         "responseImage": {
             "brand": "Rheem",
             "model_number": "RAKA-037JAZ",
             "serial_number": "5429.M4200 04207",
             "matched_brand": null,
             "capacity_btus": null,
             "voltage": "208/230 V",
             "phase": "1",
             "refrigerant_type": "R22",
             "manufacturing_date": "2000-10",
             "configuration_type": null,
             "amperage": null,
             "hertz": "60",
             "fan": null,
             "compressor_1": {
                "lra": "95"
             },
             "compressor_2": null,
             "compressor_3": null,
             "compressor_4": null,
             "pressure_ratings": {
                "high_side": "300 PSIG",
                 "low_side": "150 PSIG"
             },
             "warranty_prediction": "Warranty information not sufficient to determine",
             "serial_number_extra_data": {
                "manufacturing_date": {
                   "year": null,
                   "month": null,
                    "week": null,
                    "error": "Serial number format not recognized for RHEEM"
                },
                "warranty": {
                   "standard_warranty_registered": 10,
           "standard_warranty_unregistered": 5,
                   "parts_warranty_registered": 10,
                   "parts_warranty_unregistered": 5,
                   "compressor_warranty": null,
                   "heat_exchanger_warranty": 20,
                   "lifetime_warranty": null,
                   "no_hassle_warranty": "yes",
                   "labor_warranty": null,
                   "extended_warranty": null,
                   "conditional_unit_replacement_warranty": "yes",
                   "transferrable": null,
                   "warranty_details": "RHEEM provides a 10-year limited parts warranty and 20-year warranty on heat exchangers for most furnaces. Select models offer a Conditional Unit Replacement Warranty for heat exchanger or compressor failures."
                }
             },
            "image": "data:image/png;base64,iVBORw0KGgoAA7KemECys/Zh...RU5ErkJggg=="
          },
          "connectedModel": {
             "id": "5CAFCBD7-5D09-4695-BA66-25BCDF0130BB",
             "model": "RAKA-037JAZ",
             "model_notes": "280-230V, 1Ph (COMP ID 5407)",
             "logo": "https://assets-bluon-prod.sfo3.c...9CIXRYWaCelLFMJW_rheem.png",
             "image": "https://assets-bluon-prod.sfo3.cdn.digitaloce...ge/RAKAPIC.png",
             "brand_name": "Rheem",
             "brand_image": "https://assets-bluon-prod.sfo3...CCelLFMJW_rheem.png"
           }
       }
    }
}

responseImage object

Attribute	Description
`brand`	Manufacturer or brand name as detected from the nameplate
`model_number`	Specific model identifier of the unit
`serial_number`	Serial identifier unique to the equipment, which may indicate manufacturing details
`capacity_btus`	Cooling or heating capacity
`voltage`	Operational voltage range of the equipment
`phase`	Electrical phase type
`refrigerant_type`	Type of refrigerant used
`manufacturing_date`	Date the unit was manufactured
`configuration_type`	Equipment configuration
`amperage`	Electrical current rating for the unit
`hertz`	Frequency of the electrical supply
`fan`	Details about the fan, if mentioned
`compressor`	Information about the compressor
`pressure_ratings`	High and low operating pressures, if specified on the nameplate
`warranty_prediction`	A prediction of whether the unit is likely under warranty, based on the manufacturing date and brand's warranty details
`serial_number_extra_data`	Extra information related to the serial number

connectedModel object

Attribute	Description
`id`	Unique identifier of the connected model in the database
`model`	Specific model number of the detected unit
`model_notes`	Additional notes regarding the model configuration, such as voltage and phase type
`logo`	URL of the brand's logo associated with the model
`image`	URL of the representative image of the detected unit
`brand_name`	Manufacturer or brand name of the equipment
`brand_image`	URL of the manufacturer's brand logo image

8. Summary of shortcut examples

Here we provide a quick access guide to the main features of FSM using the appropriate combination of parameters explained in the corresponding section. If the solution is being implemented in an app, the device parameter must also be included.

HVAC Tools

The main menu of the Bluon FSM Webview tool provides access to four primary options. There may be fewer options available if the necessary permissions to access certain features are not granted.

•Get HVAC A.I. Support
•Scan a Nameplate
•Search Models
•Search Parts

https://[domain]?id=iframe&mode=fsm&origin=app&view=hvac-tools&showTabs=false

Bluon AI

Provides access to MasterMechanic, Bluon's AI assistant designed to help technicians resolve every kind of troubleshooting and service scenario in the field, as well as provide quick responses to manuals and parts questions. Note: MasterMechanic is our default name, but it can be white labeled to fit your brand.

https://[domain]?id=iframe&mode=fsm&origin=app&view=master-mechanics&showTabs=false

Scan nameplate

Enables model search by capturing a photo or uploading an image. You can also enable or disable the option to perform a manual search using the 'showManually' parameter.

With showManually set to true:

https://[domain]?id=iframe&mode=fsm&origin=app&view=search&showTabs=false&tab=models&searchMode=asset&isNameplateReaderModal=true&showManually=true

With showManually set to false:

https://[domain]?id=iframe&mode=fsm&origin=app&view=search&showTabs=false&tab=models&searchMode=asset&isNameplateReaderModal=true&showManually=false

Search only Models

Allows searching by model number or brand, providing access to manuals, parts lists, and other relevant information about the selected model. Additionally, it includes a direct link to Get HVAC A.I. Support, enabling users to make inquiries directly related to the selected model.

Some features may not be available if the required permissions are not granted

https://[domain]?id=iframe&mode=fsm&origin=app&view=search&showTabs=false&tab=models

Search only Parts

Allows searching by part number. Once a part is selected from the available list, users can view its details, copy the information, and explore possible replacements within the platform.

Some features may not be available if the required permissions are not granted.

https://[domain]?id=iframe&mode=fsm&origin=app&view=search&showTabs=false&tab=parts

Search by Models or Parts

Combines the power of the previously mentioned model and part searches with the ability to switch between search types at any time using the available tabs.

https://[domain]?id=iframe&mode=fsm&origin=app&view=search&showTabs=true

Search with an initial search

Allows the search screen to be displayed with a search already performed. This can apply to either models or parts, depending on the value of the 'tab' parameter.

Model:

https://[domain]?id=iframe&mode=fsm&origin=app&view=search&showTabs=false&tab=models&initSearch=123

Part:

https://[domain]?id=iframe&mode=fsm&origin=app&view=search&showTabs=false&tab=parts&initSearch=123

Model Detail page with a model Id

If a model ID (UUID) is available, it is possible to access the model's detailed information directly without going through the search. This ID is one of the values returned in the previously mentioned 'add-job' event.

https://[domain]?id=iframe&mode=fsm&origin=app&view=search&showTabs=false&tab=models&modelDetail=1F5EC8C3-629E-4B9F-9B35-B3B4D910643C

Asset flow - Add Job

Enables the Asset flow, allowing a scan or manual search to associate the result with a model in the system and load the job accordingly. This flow is what ultimately triggers the previously described event.

https://[domain]?id=iframe&mode=fsm&origin=app&view=search&tab=models&searchMode=asset&showManually=true&isNameplateReaderModal=true&showTabs=false

9. Troubleshooting

Some common issues that may arise during the implementation of the iframe and how to resolve them. Proper configuration is essential for smooth functionality, so these troubleshooting steps will help identify and fix common problems.

Authentication Failure

Authentication fails due to an incorrect domain (for web implementations) or an incorrect key (for app implementations).

Solution:

•Web Implementation: Ensure that the domain used to embed the iframe matches the one registered with Bluon.
•App Implementation: Verify that the provided Key is correct and associated with the correct account.
•Check for typos or missing characters in the key.
•Ensure the key has the required permissions.

Access Denied to a Restricted Page

Attempting to access a page for which you do not have the necessary permissions.

Solution:

•Confirm that your account has the appropriate permissions to access the requested page.
•Check the configuration settings to ensure that the requested resource is included in your access scope.
•Contact support if access should be granted but is being denied, as there may be a configuration issue on the server side.