Заявете ранен достъп

Посочете името си и имейл адрес или телефонен номер. Ще Ви изпратим информация за достъп до Tajo.

На тази страница

Връзки за инсталация и дълбоки връзки

Връзките за инсталация Ви позволяват да разпространявате Вашето Stripe App извън marketplace, а дълбоките връзки насочват потребителите директно към конкретни изгледи във вече инсталираното приложение. И двете са съществени за плавно въвеждане в работа и за интеграционните процеси.

Връзки за инсталация

Връзките за инсталация предоставят директен URL адрес, който търговците могат да използват, за да инсталират Вашето приложение. Когато потребител кликне върху връзка за инсталация, Stripe провежда процеса на инсталация и след това го пренасочва обратно към посочения от Вас адрес.

Предварителни изисквания

Преди да използвате връзки за инсталация, конфигурирайте 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`	Да	Идентификаторът на Вашето приложение (например `com.tajo.brevo-integration`)
`redirect_uri`	Да	Трябва да съвпада с един от Вашите `allowed_redirect_uris`
`state`	Препоръчително	Случаен низ за защита от CSRF

Параметри при пренасочване

След успешна инсталация Stripe пренасочва потребителя към Вашия redirect_uri със следните параметри в заявката:

Параметър	Описание
`user_id`	Идентификаторът на потребителя в Stripe, който инсталира приложението
`account_id`	Идентификаторът на акаунта в Stripe (например `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 Dashboard в настройките на приложението. Използвайте я, за да:

Проверявате подписите за инсталация от обратните извиквания при пренасочване
Валидирате данните от webhooks от Stripe
Удостоверявате заявките между Вашия бекенд и 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 акаунт	`acct_1234567890`
`PAGE`	Път до страница в Dashboard	`customers/cus_xxxxx`
`APP_ID`	Идентификаторът на Вашето приложение	`com.tajo.brevo-integration`
`TARGET`	`drawer` или `modal`	`drawer`
`VIEWPORT_ID`	Viewport, който да се отвори	`stripe.dashboard.customer.detail`

Цел	Поведение	Приложение
`drawer`	Отваря приложението в страничния панел (drawer)	Стандартно взаимодействие с приложението, контекст успоредно със страницата
`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>

Комбиниране на връзки за инсталация и дълбоки връзки

За най-добро изживяване при въвеждане в работа комбинирайте връзките за инсталация с дълбоки връзки след инсталация:

Потребителят кликва върху връзка за инсталация от Вашия уебсайт или имейл
Потребителят инсталира приложението и е пренасочен към Вашия адрес за обратно извикване
Вашето обратно извикване обработва инсталацията и пренасочва потребителя към дълбока връзка, която отваря 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, така и в тестов режим, за да сте сигурни, че работят правилно във всички среди.