Integrating Protocol Requests (Deeplinks) in PatchKit Launcher SDK

What Are Protocol Requests (Deeplinks)?

Protocol requests, often referred to as deeplinks, enable external applications or websites to trigger specific actions in your application via custom URL schemes. They act as a bridge between systems, making it easier to integrate functionalities across platforms.

How Do They Work?

Protocol Registration: The application registers itself as a handler for a specific protocol (e.g., my-app://).
Request Handling: The application processes protocol requests, such as my-app://do-action.
Triggering Requests: External sources, such as websites or other apps, invoke these requests. For example, a “Download” button on a game’s webpage might link to my-app://download-game?id=123.

Example of a Protocol Request in Chrome Browser:
Protocol Request Example

Configuring Protocol Support in PatchKit Launcher SDK

Adding protocol support to your launcher in the PatchKit SDK is straightforward. All you need is to configure the protocol field in your preset.

Example Configuration

// ...
protocol: {
  id: "patchkit-demo-launcher"
}
// ...

Testing Protocol Support

To confirm the setup:

Start your launcher in development mode.
Trigger a protocol request, such as patchkit-demo-launcher://test.
Ensure the launcher opens and focuses as expected.

Customization Options:

isAutoShowingWindowOnProtocolPendingRequestRegisteredEnabled: Controls whether the launcher window auto-opens on a protocol request.
isAutoFocusingWindowOnProtocolPendingRequestRegisteredEnabled: Controls whether the launcher auto-focuses on a protocol request.

Note: Updating the protocol field requires publishing a new version of your runtime to deploy changes.

Handling Protocol Requests in React Themes

The @upsoft/patchkit-launcher-runtime-api-react-theme-extras package simplifies handling protocol requests in React.

Using the `useProtocolPendingRequestListener` Hook

The useProtocolPendingRequestListener hook listens for incoming protocol requests and allows you to define how they’re handled.

Here’s an example implementation:

import { startAppBranchProcess } from "@upsoft/patchkit-launcher-runtime-api-react-theme-client";
import { useProtocolPendingRequestListener } from "@upsoft/patchkit-launcher-runtime-api-react-theme-extras";
import { useCallback } from "react";

export function App() {
  useProtocolPendingRequestListener(
    useCallback(async ({ protocolPendingRequestController }) => {
      const url = protocolPendingRequestController.url;

      if (url.includes("://start-app-branch-process")) {
        await protocolPendingRequestController.dismiss();
        
        const urlObject = new URL(url);
        const appId = urlObject.searchParams.get("appId");
        const appBranchId = urlObject.searchParams.get("appBranchId");

        if (appId && appBranchId) {
          await startAppBranchProcess({ appId, appBranchId });
        }
      }
    }, [])
  );

  // Component rendering logic...
}

Best Practices:

Place the hook in a top-level component like <App> or context providers to ensure it remains active.

Handling Protocol Requests in Non-React Themes

For non-React themes, the @upsoft/patchkit-launcher-runtime-api-theme-client package provides two core functions:

fetchProtocolPendingRequestsInfo: Retrieves pending protocol requests.
dismissProtocolPendingRequest: Dismisses a pending protocol request after processing.

Refer to the API documentation for detailed usage examples.

Summary

Protocol requests (deeplinks) offer a powerful way to integrate your PatchKit launcher with other systems. They allow you to create seamless workflows between websites, applications, and the launcher. Whether you’re working in React or a custom theme, PatchKit provides the tools you need to handle protocol requests effectively.

Key Takeaways:

Configuration: Add the protocol field to your preset to enable protocol support.
React Handling: Use The useProtocolPendingRequestListener hook for streamlined integration in React themes.
Non-React Handling: Use the fetchProtocolPendingRequestsInfo and dismissProtocolPendingRequest functions for other themes.
Flexibility: Customize behavior to suit your application’s needs and improve user experience.

Get started by enabling protocol support and experimenting with deeplinks today!

Integrating Protocol Requests (Deeplinks)