✨ (ledger-button) [NO-ISSUE]: Add deep link tracking params for analytics (#285)

Author: mbertin-ledger

packages/ledger-button/src/domain/home/ledger-home.ts

@@ -161,9 +161,13 @@ export class LedgerHomeScreen extends LitElement {
 
     void this.coreContext.trackWalletRedirectConfirmed(action);
 
-    const deeplink = buildWalletActionDeepLink(action, {
-      currency: this.controller.selectedAccount?.currencyId,
-    });
+    const deeplink = buildWalletActionDeepLink(
+      action,
+      {
+        currency: this.controller.selectedAccount?.currencyId,
+      },
+      this.coreContext.getConfig().dAppIdentifier,
+    );
     window.open(deeplink, "_blank", "noopener,noreferrer");
 
     this.showRedirectDrawer = false;

packages/ledger-button/src/shared/constants/deeplinks.test.ts

@@ -0,0 +1,73 @@
+import { describe, expect, test } from "vitest";
+
+import { buildWalletActionDeepLink } from "./deeplinks.js";
+
+describe("buildWalletActionDeepLink", () => {
+  describe("without partner", () => {
+    test("returns base URL when no context", () => {
+      expect(buildWalletActionDeepLink("swap")).toBe("ledgerwallet://swap");
+      expect(buildWalletActionDeepLink("send")).toBe("ledgerwallet://send");
+      expect(buildWalletActionDeepLink("buy")).toBe("ledgerwallet://buy");
+    });
+
+    test("appends currency params when context has currency", () => {
+      expect(buildWalletActionDeepLink("send", { currency: "eth" })).toBe(
+        "ledgerwallet://send?currency=eth",
+      );
+      expect(buildWalletActionDeepLink("swap", { currency: "usdc" })).toBe(
+        "ledgerwallet://swap?fromToken=usdc",
+      );
+      expect(buildWalletActionDeepLink("earn", { currency: "btc" })).toBe(
+        "ledgerwallet://earn?cryptoAssetId=btc",
+      );
+    });
+  });
+
+  describe("with partner", () => {
+    test("appends tracking query params with fixed deeplinkType and deeplinkChannel", () => {
+      const url = buildWalletActionDeepLink("swap", undefined, "MyPartner");
+      expect(url).toContain("deeplinkType=Internal");
+      expect(url).toContain("deeplinkChannel=Button");
+      expect(url).toContain("deeplinkDestination=swap");
+      expect(url).toContain("deeplinkButtonPartner=MyPartner");
+    });
+
+    test("maps each action to correct deeplinkDestination (same as route)", () => {
+      const partner = "Partner";
+      expect(buildWalletActionDeepLink("send", undefined, partner)).toContain(
+        "deeplinkDestination=send",
+      );
+      expect(buildWalletActionDeepLink("receive", undefined, partner)).toContain(
+        "deeplinkDestination=receive",
+      );
+      expect(buildWalletActionDeepLink("swap", undefined, partner)).toContain(
+        "deeplinkDestination=swap",
+      );
+      expect(buildWalletActionDeepLink("buy", undefined, partner)).toContain(
+        "deeplinkDestination=buy",
+      );
+      expect(buildWalletActionDeepLink("earn", undefined, partner)).toContain(
+        "deeplinkDestination=earn",
+      );
+      expect(buildWalletActionDeepLink("sell", undefined, partner)).toContain(
+        "deeplinkDestination=buy",
+      );
+    });
+
+    test("preserves existing currency params when partner is provided", () => {
+      const url = buildWalletActionDeepLink(
+        "swap",
+        { currency: "eth" },
+        "MyPartner",
+      );
+      expect(url).toContain("fromToken=eth");
+      expect(url).toContain("deeplinkType=Internal");
+      expect(url).toContain("deeplinkButtonPartner=MyPartner");
+    });
+
+    test("URL-encodes partner with special characters", () => {
+      const url = buildWalletActionDeepLink("buy", undefined, "Partner & Co");
+      expect(url).toContain("deeplinkButtonPartner=Partner+%26+Co");
+    });
+  });
+});

packages/ledger-button/src/shared/constants/deeplinks.ts

@@ -8,17 +8,18 @@ export type DeepLinkContext = {
   address?: string;
 };
 
+const BASE_URL = "ledgerwallet://";
 /**
  * Base deep links for wallet actions.
  * Note: "sell" is not supported in Ledger Live Desktop, falls back to "buy".
  */
 const BASE_DEEPLINKS: Record<WalletTransactionFeature, string> = {
-  send: "ledgerwallet://send",
-  receive: "ledgerwallet://receive",
-  swap: "ledgerwallet://swap",
-  buy: "ledgerwallet://buy",
-  earn: "ledgerwallet://earn",
-  sell: "ledgerwallet://buy",
+  send: "send",
+  receive: "receive",
+  swap: "swap",
+  buy: "buy",
+  earn: "earn",
+  sell: "buy",
 };
 
 /**
@@ -31,30 +32,50 @@ const BASE_DEEPLINKS: Record<WalletTransactionFeature, string> = {
  * - buy: no params (params passed through to liveApp)
  * - earn: ?cryptoAssetId={currency} (pre-fills asset for deposit)
  * - sell: not supported in Desktop, falls back to buy
+ *
+ * When partner is provided, appends tracking query params: deeplinkType, deeplinkDestination,
+ * deeplinkChannel, deeplinkButtonPartner (for deeplink_clicked analytics).
  */
 export function buildWalletActionDeepLink(
   action: WalletTransactionFeature,
   context?: DeepLinkContext,
+  partner?: string,
 ): string {
-  const baseUrl = BASE_DEEPLINKS[action];
+  const route = BASE_DEEPLINKS[action];
+  const baseUrl = `${BASE_URL}${route}`;
 
+  let urlString: string;
   if (!context?.currency) {
-    return baseUrl;
+    urlString = baseUrl;
+  } else {
+    switch (action) {
+      case "send":
+      case "receive":
+        urlString = `${baseUrl}?currency=${context.currency}`;
+        break;
+      case "swap":
+        urlString = `${baseUrl}?fromToken=${context.currency}`;
+        break;
+      case "earn":
+        urlString = `${baseUrl}?cryptoAssetId=${context.currency}`;
+        break;
+      case "buy":
+      case "sell":
+      default:
+        urlString = baseUrl;
+    }
   }
 
-  switch (action) {
-    case "send":
-    case "receive":
-      return `${baseUrl}?currency=${context.currency}`;
-    case "swap":
-      return `${baseUrl}?fromToken=${context.currency}`;
-    case "earn":
-      return `${baseUrl}?cryptoAssetId=${context.currency}`;
-    case "buy":
-    case "sell":
-    default:
-      return baseUrl;
+  if (!partner) {
+    return urlString;
   }
+
+  const url = new URL(urlString);
+  url.searchParams.set("deeplinkType", "Internal");
+  url.searchParams.set("deeplinkDestination", route);
+  url.searchParams.set("deeplinkChannel", "Button");
+  url.searchParams.set("deeplinkButtonPartner", partner);
+  return url.toString();
 }
 
 /**