How to Create Application Shortcuts
Introduction
Shortcuts provide users with an easy way to access applications directly from their desktop or Start Menu. However, creating shortcuts that interact with launchers can be more complex than pointing to an executable file. Many launchers need to pass additional arguments or environment variables to start applications properly. In such cases, using deeplinks offers a robust solution for routing shortcut actions through the launcher.
In this guide, we’ll walk you through the process of creating shortcuts for launching applications with the PatchKit Launcher SDK using protocol-based deeplinks.
Why Use Deeplinks for Shortcuts?
Traditional shortcuts directly link to executable files, but this approach has limitations when additional configuration or arguments are required. By using protocol-based deeplinks, you can:
- Ensure compatibility with your launcher’s processes.
- Centralize logic for handling application launches.
- Dynamically pass application-specific data (e.g., access tokens, configurations).
Prerequisites
Before proceeding, ensure you’ve followed the Protocol Requests (Deeplinks) Integration Guide to set up your launcher for handling protocol-based actions.
Step 1: Creating Shortcuts with Protocols
The following example demonstrates how to create shortcuts that use deeplinks to initiate application launches. These shortcuts are generated in the system’s default shortcut directory (e.g., Desktop or Start Menu).
Code Example: createAppBranchDesktopShortcut
import {
AppBranchInfo,
AppInfo,
createShortcut,
PROTOCOL_INFO,
ShortcutIconSourceType,
} from "@upsoft/patchkit-launcher-runtime-api-react-theme-client";
export async function createAppBranchDesktopShortcut(
{
appInfo,
appBranchInfo,
}: {
appInfo: AppInfo;
appBranchInfo: AppBranchInfo;
},
) {
try {
if (!appInfo.iconUrl) {
return;
}
await createShortcut({
shortcutPathTemplate: `{defaultShortcutsDirPath}/${appInfo.name ?? appInfo.id}`,
shortcutIconSourceInfo: {
type: ShortcutIconSourceType.UrlSource,
url: appInfo.iconUrl,
},
shortcutUrl: `${PROTOCOL_INFO.value!.id}://start-app-branch-process?appId=${appInfo.id}&appBranchId=${appBranchInfo.id}`,
});
} catch (error) {
console.error("Error creating shortcut:", error);
}
}
Key Details:
- Shortcut Location: Defaults to the Desktop directory. For Windows, use
{windowsStartMenuDirPath}to place shortcuts in the Start Menu. - Dynamic Icon and Name: Shortcut appearance is customized based on
AppInfo(make sure name and icon for your application are set in App Catalog). - Protocol-Based Action: The
shortcutUrlincludes a deeplink with parameters likeappIdandappBranchId.
For more options, see the createShortcut API documentation.
Step 2: Handling Protocol Requests
The next step is to handle the deeplinks used by the shortcuts. To do this, you’ll use the useProtocolPendingRequestListener hook in a global component of your launcher theme (e.g., <Root> or <App>).
Code Example: Protocol Handler
import { useEffect } from "react";
import { useProtocolPendingRequestListener } from "@upsoft/patchkit-launcher-runtime-api-react-theme-extras";
import { startAppBranchProcess } from "./app-branch-process";
export function ProtocolHandler() {
useProtocolPendingRequestListener((request) => {
const url = new URL(request.url);
if (url.pathname === "start-app-branch-process") {
const appId = url.searchParams.get("appId");
const appBranchId = url.searchParams.get("appBranchId");
if (appId && appBranchId) {
startAppBranchProcess({ appId, appBranchId });
}
}
});
return null;
}
Explanation:
useProtocolPendingRequestListener: Listens for incoming protocol requests.- URL Parsing: Identifies the protocol action (
start-app-branch-process) and extracts query parameters (appIdandappBranchId). - Custom Logic: The
startAppBranchProcessfunction handles the app’s launch process.
Ensure this component is always rendered within your application.
Step 3: Using the Shortcut Functionality
With the shortcut creation and protocol handling logic in place, you can now integrate this functionality into your launcher theme.
Code Example: Adding a Shortcut Creation Button
import { useAppInfo } from "@upsoft/patchkit-launcher-runtime-api-react-theme-client";
import { createAppBranchDesktopShortcut } from "./create-app-branch-shortcut";
export function AppSettings(
{
appId,
appBranchId,
}: {
appId: string;
appBranchId: string;
},
) {
const appInfo = useAppInfo({ appId });
return (
<div>
<button
onClick={async () => {
if (appInfo) {
await createAppBranchDesktopShortcut({
appInfo,
appBranchInfo: { id: appBranchId },
});
}
}}
>
Create Shortcut
</button>
</div>
);
}
This component adds a button for creating a shortcut for a specific application and branch.
Summary
In this guide, we demonstrated how to create shortcuts for starting applications using the PatchKit Launcher SDK and protocol-based deeplinks. By implementing the provided code:
- You can generate shortcuts with custom names and icons that point to specific launcher actions.
- The launcher can handle these protocol requests to initiate the appropriate application branch process.
- You can integrate shortcut creation functionality seamlessly into your launcher’s theme.
This approach simplifies managing complex launch logic and enhances the user experience by providing intuitive shortcuts.
Start implementing this functionality today and streamline your application launches!
