buildfire.deeplink

This is an object within the buildfire singleton that is responsible for receiving deep link data and compiling deep links for use.

What is a deep link?

a deep link is similar to a URL you use on the web. However, it has two major distinctions.

• the protocol is different the your standard http:// or https://
• and it doesn't trigger your browser to open up a page

It relies on applications installed on your device that assumes the responsibility of handing that custom protocol/schema. In this case, it would be your app. With a deep link and the app installed you can not only open the app with the link, you can drill down to a particular plugin. That functionality is taken care of by the BuildFire framework.

There are some times where you would want to drill down even further into a plugin. This is where the custom development comes in.

A deeplink can also be registered to be used with action items allowing the user to navigate to your plugin passing the data you have already registered.

tip

To create URLs that can be shared with devices not requiring prior app installation, refer to Share Links and Deep Linking.

Methods

registerDeeplink()

buildfire.deeplink.registerDeeplink(options, callback)

Registers a deeplink into the appData. Registered deeplinks can be selected in the Control Panel action item dialogs as highlighted below:

In this example the developer has registered a deeplink with the name "John Doe" so that when the action item is executed it would navigate to the plugin passing the data that identifies "John Doe" allowing the plugin to internally navigate to that person.

For more info about action items dialog on control side please refer to action-Items.

buildfire.deeplink.registerDeeplink(
  {
    id: "PERSON-431",
    name: "John Doe",
    deeplinkData: { personId: "PERSON-431" },
  },
  (err, result) => {
    if (err) return console.log(err);
    console.log("INSERTED/UPDATED DEEPLINK", result);
  }
);

options

Name	Type	Required	Description	Default
id	string	yes	Id of the deeplink record
name	string	yes	The name of the deeplink in action items dialog
deeplinkData	object	yes	Custom object that will be sent when navigating to the plugin through the action item
imageUrl	string	no	An image url to show next to the deeplink in action items dialog

callback(err, deepLink)

Callback function that will be executed when the insertion is finished

Name	Type	Description
err	string	Error string, or null when operation is successful
deepLink	object	Inserted or updated deeplink

deepLink

Name	Type	Description
deeplinkData	object	Custom object that will be sent when navigating to the plugin through the action item
deeplinkId	string	Id of the deeplink record
name	string	The name of the deeplink in action items dialog
pluginInstanceId	string	Plugin instance id of the plugin where deep link can be used
pluginTypeId	string	Plugin type id of the plugin where deep link can be used

---

getDeeplink()

buildfire.deeplink.getDeeplink(deeplinkId, callback)

Gets a deeplink by the deeplinkId

buildfire.deeplink.getDeeplink("PERSON-431", (err, result) => {
  if (err) return console.log(err);
  if (result) {
    console.log("Deep link found", result.data);
  } else {
    console.log("Deep link not found");
  }
});

deeplinkId

Name	Type	Description
deeplinkId	string	Id of the deeplink record

callback(err, result)

Callback function after operation is complete

Name	Type	Description
err	string	Error string, null when operation is successful
result	number	Result object containing deep link in data property. result.data is in deepLink format

---

getAllDeeplinks()

buildfire.deeplink.getAllDeeplinks(options, callback)

Gets all the deeplinks from the appData according to the plugin instanceId

buildfire.deeplink.getAllDeeplinks(null, (err, results) => {
  if (err) return console.log(err);
  if (results) {
    console.log(
      "ALL DEEPLINKS",
      results.map((result) => result.data)
    );
  }
});

options

Reserved for future usage. can be passed as null.

callback(err, results)

Callback function after something is done

Name	Type	Description
err	string	Error string, null when operation is successful
results	[object]	Array of objects containing deep link in data property. result[].data is in deepLink format

---

unregisterDeeplink()

buildfire.deeplink.unregisterDeeplink(deeplinkId, callback)

Deletes / unregisters a deep link.

buildfire.deeplink.unregisterDeeplink("PERSON-431", (err, result) => {
  if (err) return console.log(err);
  console.log("DELETED DEEPLINK", result);
});

deeplinkId

Name	Type	Description
deeplinkId	string	Id of the deeplink record

callback(err, result)

Callback function after something is done

Name	Type	Description
err	string	Error string, null when operation is successful
result	object	{"success": true} when operation is successful, undefined otherwise

---

getData()

buildfire.deeplink.getData(callback)

Used to fetch the deep link data if any was passed down to plugin.

buildfire.deeplink.getData((deeplinkData) => {
  if (deeplinkData) console.log("Deep link data: ", deeplinkData);
});

callback(deeplinkData)

Callback function with link data

Name	Type	Description
deeplinkData	object	Object with custom deep link data

---

onUpdate()

buildfire.deeplink.onUpdate(callback, allowMultipleHandlers)

Listens for any deeplink updates. Executed whenever a new deeplink is passed to the plugin.

buildfire.deeplink.onUpdate((deeplinkData) => {
  if (deeplinkData) console.log("Deep link data: ", deeplinkData);
}, true);

callback(deeplinkData)

Callback function with link data

Name	Type	Description
deeplinkData	object	Object with custom deep link data

allowMultipleHandlers

Name	Type	Required	Description	Default
allowMultipleHandlers	boolean	no	Tells the method to override all other handlers, or allow multiple handlers to exist at the same time	false

---

createLink() Deprecated

buildfire.deeplink.createLink(obj)

Returns the deep link URL for your plugin with the attached Deep Link Data.

let link = buildfire.deeplink.createLink({data: "Mydata"});

callback(err, deeplink)

Takes in an object or string and compiles a deep link so that the user may use the link to send others directly into the widget subsection (obsolete)