申请抢先体验

请填写名字，以及邮箱或手机号。我们会与您联系，提供 Tajo 访问详情。

在本页面

安装链接与深度链接

安装链接（install links）让你在应用市场之外分发 Stripe App，深度链接（deep links）则把用户直接带到已安装应用中的特定视图。两者对顺畅的上手引导和集成流程都不可或缺。

安装链接

安装链接提供一个直接 URL，商家点击后即可安装你的应用。用户点击安装链接时，Stripe 会处理安装流程，然后重定向回你指定的 URI。

前提条件

使用安装链接之前，先在应用清单（app manifest）中配置 allowed_redirect_uris：

{
  "id": "com.tajo.brevo-integration",
  "allowed_redirect_uris": [
    "https://tajo.io/stripe/callback",
    "https://tajo.io/stripe/oauth/complete"
  ]
}

安装链接格式

https://marketplace.stripe.com/oauth/v2/authorize?client_id=APP_ID&redirect_uri=REDIRECT_URI&state=STATE_VALUE

参数	是否必需	说明
`client_id`	是	你的应用 ID（例如 `com.tajo.brevo-integration`）
`redirect_uri`	是	必须与 `allowed_redirect_uris` 中的某一项一致
`state`	建议	用于 CSRF 防护的随机字符串

重定向参数

安装成功后，Stripe 会把用户重定向到你的 redirect_uri，并附带以下查询参数：

参数	说明
`user_id`	执行安装的账号的 Stripe user ID
`account_id`	Stripe account ID（例如 `acct_xxxxx`）
`state`	你提供的 `state` 值（用于 CSRF 校验）
`install_signature`	用于验证安装是否合法的 HMAC 签名

重定向 URL 示例：

https://tajo.io/stripe/callback
  ?user_id=usr_xxxxx
  &account_id=acct_xxxxx
  &state=abc123random
  &install_signature=sig_xxxxx

CSRF 保护

始终使用 state 参数来防止跨站请求伪造攻击：

import crypto from 'crypto';

// Generate a random state value and store it in the session
const generateInstallLink = (req, res) => {
  const state = crypto.randomBytes(32).toString('hex');

  // Store state in session for later verification
  req.session.stripeInstallState = state;

  const installUrl = new URL('https://marketplace.stripe.com/oauth/v2/authorize');
  installUrl.searchParams.set('client_id', 'com.tajo.brevo-integration');
  installUrl.searchParams.set('redirect_uri', 'https://tajo.io/stripe/callback');
  installUrl.searchParams.set('state', state);

  res.redirect(installUrl.toString());
};

// Handle the redirect callback
const handleInstallCallback = async (req, res) => {
  const { state, user_id, account_id, install_signature } = req.query;

  // Verify state matches what we stored
  if (state !== req.session.stripeInstallState) {
    return res.status(403).json({ error: 'Invalid state parameter' });
  }

  // Clear the stored state
  delete req.session.stripeInstallState;

  // Verify the install signature
  if (!verifyInstallSignature(install_signature, account_id)) {
    return res.status(403).json({ error: 'Invalid install signature' });
  }

  // Process the successful installation
  await processInstallation(user_id, account_id);

  res.redirect('/dashboard/stripe-connected');
};

签名验证

使用应用的签名密钥（signing secret）验证 install_signature：

import crypto from 'crypto';

const verifyInstallSignature = (signature, accountId) => {
  const signingSecret = process.env.STRIPE_APP_SIGNING_SECRET;

  const expectedSignature = crypto
    .createHmac('sha256', signingSecret)
    .update(accountId)
    .digest('hex');

  return crypto.timingSafeEqual(
    Buffer.from(signature),
    Buffer.from(expectedSignature)
  );
};

Caution

比较签名时始终使用 crypto.timingSafeEqual，以防时序攻击。不要使用简单的字符串相等判断（===）。

签名密钥

你的应用签名密钥可以在 Stripe Dashboard 的应用设置中找到。它的用途包括：

验证重定向回调中的安装签名
校验来自 Stripe 的 webhook 负载
为后端与 Stripe 之间的请求做身份认证

请妥善存储签名密钥：

# Set as environment variable
export STRIPE_APP_SIGNING_SECRET="whsec_xxxxx"

不要把签名密钥硬编码在源代码里，也不要提交到版本控制。

深度链接

深度链接把用户直接带到已安装 Stripe App 中的某个视图。用它可以把用户从外部沟通渠道（邮件、通知、支持页面）引导到相关的应用上下文。

深度链接 URL 格式

https://dashboard.stripe.com/MODE/acct_ID/PAGE?apps[APP_ID][TARGET]=VIEWPORT_ID

组成部分	说明	示例
`MODE`	`live` 或 `test`	`live`
`acct_ID`	目标 Stripe account ID	`acct_1234567890`
`PAGE`	Dashboard 页面路径	`customers/cus_xxxxx`
`APP_ID`	你的应用 ID	`com.tajo.brevo-integration`
`TARGET`	`drawer` 或 `modal`	`drawer`
`VIEWPORT_ID`	要打开的 viewport	`stripe.dashboard.customer.detail`

目标	行为	适用场景
`drawer`	在侧边面板（drawer）中打开应用	默认的应用交互，在页面旁提供上下文
`modal`	在全屏 modal 浮层中打开应用	需要专注的工作流、上手引导、复杂表单

深度链接示例

在 drawer 中打开客户详情视图

https://dashboard.stripe.com/live/acct_xxxxx/customers/cus_xxxxx
  ?apps[com.tajo.brevo-integration][drawer]=stripe.dashboard.customer.detail

https://dashboard.stripe.com/live/acct_xxxxx/settings
  ?apps[com.tajo.brevo-integration][modal]=stripe.dashboard.settings

打开上手引导流程

https://dashboard.stripe.com/live/acct_xxxxx/dashboard
  ?apps[com.tajo.brevo-integration][modal]=stripe.dashboard.onboarding

在测试模式下打开支付详情视图

https://dashboard.stripe.com/test/acct_xxxxx/payments/pi_xxxxx
  ?apps[com.tajo.brevo-integration][drawer]=stripe.dashboard.payment.detail

以编程方式生成深度链接

const generateDeepLink = ({
  accountId,
  mode = 'live',
  page,
  appId = 'com.tajo.brevo-integration',
  target = 'drawer',
  viewport,
}) => {
  const baseUrl = `https://dashboard.stripe.com/${mode}/${accountId}/${page}`;
  const params = new URLSearchParams();
  params.set(`apps[${appId}][${target}]`, viewport);

  return `${baseUrl}?${params.toString()}`;
};

// Generate a link to view a customer's Brevo profile
const customerLink = generateDeepLink({
  accountId: 'acct_xxxxx',
  page: 'customers/cus_xxxxx',
  viewport: 'stripe.dashboard.customer.detail',
});

// Generate a link to app settings
const settingsLink = generateDeepLink({
  accountId: 'acct_xxxxx',
  page: 'settings',
  viewport: 'stripe.dashboard.settings',
  target: 'modal',
});

在对外沟通中使用深度链接

深度链接在以下场景尤其有用：

邮件通知：“查看该客户的 Brevo 同步状态”
支持回复：“点击这里查看你的集成设置”
上手引导邮件：“完成你的 Brevo 配置”
错误告警：“查看客户 X 的同步问题”

<!-- Example in an email template -->
<a href="https://dashboard.stripe.com/live/acct_xxxxx/customers/cus_xxxxx?apps[com.tajo.brevo-integration][drawer]=stripe.dashboard.customer.detail">
  View Brevo Profile in Stripe
</a>

结合使用安装链接与深度链接

要获得最佳的上手体验，把安装链接和安装后的深度链接串起来：

用户在你的网站或邮件中点击 安装链接
用户完成应用安装，并被重定向到你的回调 URL
你的回调处理这次安装，然后把用户重定向到一个 深度链接，打开上手引导 viewport

const handleInstallCallback = async (req, res) => {
  const { account_id, install_signature, state } = req.query;

  // Verify state and signature
  // ... (verification code)

  // Process installation
  await processInstallation(account_id);

  // Redirect to the app's onboarding view via deep link
  const onboardingLink = generateDeepLink({
    accountId: account_id,
    page: 'dashboard',
    viewport: 'stripe.dashboard.onboarding',
    target: 'modal',
  });

  res.redirect(onboardingLink);
};

Tip

安装链接和深度链接都要在 live 和 test 两种模式下测试，确保它们在所有环境中都能正常工作。