Poproś o wcześniejszy dostęp

Podaj imię oraz adres e-mail lub numer telefonu. Wyślemy Ci informacje o dostępie do Tajo.

Na tej stronie

Linki instalacyjne i linki głębokie

Linki instalacyjne pozwalają dystrybuować aplikację Stripe poza marketplace, a linki głębokie kierują użytkowników bezpośrednio do konkretnych widoków w zainstalowanej aplikacji. Jedne i drugie są niezbędne dla płynnego wdrożenia i przebiegu integracji.

Linki instalacyjne

Linki instalacyjne udostępniają bezpośredni adres URL, którego sprzedawcy mogą użyć do zainstalowania Twojej aplikacji. Gdy użytkownik kliknie link instalacyjny, Stripe obsługuje proces instalacji, a następnie przekierowuje z powrotem pod wskazany przez Ciebie adres URI.

Wymagania wstępne

Zanim użyjesz linków instalacyjnych, skonfiguruj allowed_redirect_uris w manifeście aplikacji:

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

Format linku instalacyjnego

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

Parametr	Wymagany	Opis
`client_id`	Tak	Identyfikator Twojej aplikacji (np. `com.tajo.brevo-integration`)
`redirect_uri`	Tak	Musi pasować do jednego z Twoich `allowed_redirect_uris`
`state`	Zalecany	Losowy ciąg znaków chroniący przed atakami CSRF

Parametry przekierowania

Po udanej instalacji Stripe przekierowuje użytkownika pod Twój redirect_uri z następującymi parametrami zapytania:

Parametr	Opis
`user_id`	Identyfikator użytkownika Stripe instalującego aplikację
`account_id`	Identyfikator konta Stripe (np. `acct_xxxxx`)
`state`	Podana przez Ciebie wartość `state` (do weryfikacji CSRF)
`install_signature`	Podpis HMAC potwierdzający, że instalacja jest autentyczna

Przykładowy adres URL przekierowania:

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

Ochrona przed CSRF

Zawsze używaj parametru state, aby zapobiec atakom typu cross-site request forgery:

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');
};

Weryfikacja podpisu

Zweryfikuj install_signature przy użyciu sekretu podpisującego swojej aplikacji:

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

Do porównywania podpisów zawsze używaj crypto.timingSafeEqual, aby zapobiec atakom czasowym. Nigdy nie stosuj zwykłego porównania ciągów znaków (===).

Sekret podpisujący

Sekret podpisujący Twojej aplikacji znajdziesz w panelu Stripe w ustawieniach aplikacji. Użyj go, aby:

Weryfikować podpisy instalacji z wywołań zwrotnych przekierowania
Sprawdzać poprawność ładunków webhooków ze Stripe
Uwierzytelniać żądania między Twoim backendem a Stripe

Przechowuj sekret podpisujący w bezpieczny sposób:

# Set as environment variable
export STRIPE_APP_SIGNING_SECRET="whsec_xxxxx"

Nigdy nie umieszczaj sekretów podpisujących na stałe w kodzie źródłowym ani nie zapisuj ich w systemie kontroli wersji.

Linki głębokie

Linki głębokie kierują użytkowników bezpośrednio do konkretnego widoku w zainstalowanej aplikacji Stripe. Używaj ich, aby przenosić użytkowników z komunikacji zewnętrznej (emaili, powiadomień, stron wsparcia) do właściwego kontekstu w aplikacji.

Format adresu URL linku głębokiego

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

Element	Opis	Przykład
`MODE`	`live` lub `test`	`live`
`acct_ID`	Docelowy identyfikator konta Stripe	`acct_1234567890`
`PAGE`	Ścieżka strony w panelu	`customers/cus_xxxxx`
`APP_ID`	Identyfikator Twojej aplikacji	`com.tajo.brevo-integration`
`TARGET`	`drawer` lub `modal`	`drawer`
`VIEWPORT_ID`	Widok, który ma zostać otwarty	`stripe.dashboard.customer.detail`

Cel	Zachowanie	Zastosowanie
`drawer`	Otwiera aplikację w panelu bocznym (szufladzie)	Domyślna interakcja z aplikacją, kontekst obok strony
`modal`	Otwiera aplikację w pełnoekranowej nakładce modalnej	Skupione procesy, wdrożenie, złożone formularze

Przykłady linków głębokich

Otwarcie widoku szczegółów klienta w panelu bocznym

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

Otwarcie ustawień w oknie modalnym

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

Otwarcie procesu wdrożenia

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

Otwarcie widoku szczegółów płatności w trybie testowym

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

Generowanie linków głębokich programistycznie

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',
});

Wykorzystanie linków głębokich w komunikacji

Linki głębokie sprawdzają się szczególnie w:

Powiadomieniach email: „Zobacz status synchronizacji z Brevo dla tego klienta”
Odpowiedziach wsparcia: „Kliknij tutaj, aby sprawdzić ustawienia integracji”
Emailach wdrożeniowych: „Dokończ konfigurację Brevo”
Alertach o błędach: „Sprawdź problem z synchronizacją klienta 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>

Łączenie linków instalacyjnych z linkami głębokimi

Aby zapewnić najlepsze wdrożenie, połącz linki instalacyjne z linkami głębokimi uruchamianymi po instalacji:

Użytkownik klika link instalacyjny na Twojej stronie lub w emailu
Użytkownik instaluje aplikację i zostaje przekierowany pod Twój adres URL wywołania zwrotnego
Twoje wywołanie zwrotne przetwarza instalację i przekierowuje użytkownika do linku głębokiego, który otwiera widok wdrożenia

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

Zawsze testuj linki instalacyjne i linki głębokie zarówno w trybie live, jak i test, aby mieć pewność, że działają poprawnie we wszystkich środowiskach.