Using Deep Link Actions

Connectifi Deep Link Actions streamline outbound communication by generating URLs that can launch external applications or services directly from your FDC3-enabled app. Rather than simply broadcasting FDC3 contexts, Deep Link Actions leverage templated URLs—often including embedded context parameters—to interact with external systems seamlessly.

How They Work

Deep Link Actions come in two flavors within the Connectifi platform:

• Deep Link Actions:
These actions utilize URL templates where placeholders (e.g., {{id.email}} or {{id.ticker}}) are replaced with values from the current FDC3 context. For instance, you can launch a chat or finance app by embedding dynamic data in the URL. An example template might be:
  https://messenger.com?user={{id.email}}

• Enhanced Deep Link Actions:
These extend the basic deep linking concept by incorporating an external REST API call. When the action is triggered, your app sends the context details to an external service that computes or enriches the information, generates a final URL, and returns it. The deep link URL may be customized with additional runtime data to support more complex integrations (such as showing maps or financial quotes). This approach allows you to encapsulate business logic on an external service and then return a deep link URL for routing purposes.

How to Use Them

1. Define a URL Template:
   Decide on a URL structure that suits the target external application. Use templated parameters (wrapped with double curly braces) to represent dynamic values. For example:
     https://finance.com/quote?symbol={{id.ticker}}

2. Configure the Deep Link Action in Your App:
   Within the Connectifi platform, register the deep link action as part of your app’s configuration. This identifies how and when the action should be triggered when a corresponding intent is raised.

3. Implement the Action Handler:
   For enhanced deep links, implement a handler (typically using the Connectifi SDK) that processes the context and calls the external REST API. The external service’s response, which contains the final URL, is relayed to the consumer app that then uses it to launch the target application. You can study an example of an enhanced deep link action handler below:

   import type { LinkActionHandler } from '@connectifi/sdk';
   import { ContextTypes, type RequestError } from '@connectifi/sdk';
    
   export const generateMapLink: LinkActionHandler = async (params) => {
     const { context } = params;
     if (context.type !== 'fdc3.location') {
       throw new RequestError('Context type not supported');
     }
     
     // Example: generate a Google Maps URL dynamically
     const location = context as any; // Ensure proper type validation in production
     let url: string;
     if (location.id.geo) {
       url = `https://maps.google.com/?q=${location.id.geo.lat},${location.id.geo.long}`;
     } else {
       // Assume detailed address properties are provided
       const query = encodeURIComponent(`${location.id.address || ''}`);
       url = `https://www.google.com/maps/search/?api=1&query=${query}`;
     }
     
     return { url };
   };

4. Trigger the Action:
   Once registered, your application can raise an intent that maps to the deep link action. The Connectifi platform routes the request to your action handler, returns the deep link URL to the caller, and the external application is launched using that URL.

When to Use Deep Link Actions

• Outbound Communication:
  When you need to integrate with third-party services (e.g., messaging, finance, maps) and want users to transition from your app to those services without manual URL management.

• Enhanced Contextualization:
  For scenarios where dynamic context data is vital (like incorporating a user’s email or a source ticker) into the target URL, ensuring that the external experience aligns with the current application state.

• Custom Business Logic:
  When more sophisticated URL generation is necessary, enhanced deep links allow you to incorporate additional API logic to enrich the URL with extra parameters or validation.

Deep Link Actions showcase the power and flexibility of Connectifi by enabling your app to communicate contextually with a wide range of external services quickly and efficiently.

With little effort, you can leverage these features effectively implement dynamic navigation between systems while maintaining a consistent, context-rich user experience.