先行利用を申し込む

お名前とメールアドレスまたは電話番号をご入力ください。Tajo のアクセス方法をご案内します。

このページの内容

インストールリンクとディープリンク

インストールリンクを使うと、マーケットプレイス以外の経路で Stripe App を配布できます。一方、ディープリンクはインストール済みアプリの特定の画面へ直接ユーザーを案内します。どちらも、スムーズなオンボーディングと連携フローに欠かせません。

インストールリンク

インストールリンクは、加盟店がアプリをインストールするための直接 URL です。ユーザーがインストールリンクをクリックすると、Stripe がインストールフローを処理し、指定した URI にリダイレクトします。

前提条件

インストールリンクを使う前に、アプリのマニフェストで 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 ユーザー ID
account_idStripe のアカウント 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');
};

署名の検証

アプリの署名シークレットを使って 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 ダッシュボードのアプリ設定から取得できます。次の用途に使用します。

  • リダイレクトコールバックのインストール署名を検証する
  • Stripe から届く Webhook のペイロードを検証する
  • 自社バックエンドと Stripe の間のリクエストを認証する

署名シークレットは安全に保管してください。

Terminal window
# 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
構成要素説明例
MODElive または testlive
acct_ID対象の Stripe アカウント IDacct_1234567890
PAGEダッシュボードのページパスcustomers/cus_xxxxx
APP_IDアプリの IDcom.tajo.brevo-integration
TARGETdrawer または modaldrawer
VIEWPORT_ID開くビューポートstripe.dashboard.customer.detail

drawer と modal の使い分け

ターゲット挙動ユースケース
drawerアプリをサイドパネル（ドロワー）で開きます通常のアプリ操作、ページと並べて文脈を確認する場合
modalアプリを全画面のモーダルで開きます集中して進めるワークフロー、オンボーディング、入力項目の多いフォーム

ディープリンクの例

顧客詳細画面をドロワーで開く 

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>

インストールリンクとディープリンクを組み合わせる

オンボーディング体験を最適にするには、インストールリンクとインストール後のディープリンクを組み合わせます。

  1. ユーザーが自社サイトやメールから インストールリンク をクリックします
  2. ユーザーがアプリをインストールし、コールバック URL にリダイレクトされます
  3. コールバックでインストール処理を行い、オンボーディング用のビューポートを開く ディープリンク にユーザーをリダイレクトします
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 モードの両方でテストしてください。

先行利用を申し込む

お名前とメールアドレスまたは電話番号をご入力ください。Tajo のアクセス方法をご案内します。

自動判定
AIアシスタント

こんにちは！ドキュメントについて何でもお聞きください。