Solicită acces anticipat

Spune-ne prenumele și o adresă de e-mail sau un număr de telefon. Îți vom trimite detaliile de acces la Tajo.

Pe această pagină

Linkuri de instalare și linkuri profunde

Linkurile de instalare îți permit să îți distribui aplicația Stripe și în afara marketplace-ului, iar linkurile profunde duc utilizatorii direct într-o anumită vizualizare din aplicația deja instalată. Ambele sunt esențiale pentru fluxuri de inițiere și de integrare fără fricțiuni.

Linkuri de instalare

Linkurile de instalare oferă un URL direct pe care comercianții îl pot folosi ca să îți instaleze aplicația. Când un utilizator dă clic pe un link de instalare, Stripe se ocupă de fluxul de instalare și apoi îl redirecționează înapoi către URI-ul indicat de tine.

Cerințe preliminare

Înainte să folosești linkuri de instalare, configurează allowed_redirect_uris în manifestul aplicației tale:

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

Formatul linkului de instalare

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

Parametru	Obligatoriu	Descriere
`client_id`	Da	ID-ul aplicației tale (de exemplu `com.tajo.brevo-integration`)
`redirect_uri`	Da	Trebuie să corespundă cu una dintre valorile din `allowed_redirect_uris`
`state`	Recomandat	Șir aleatoriu pentru protecție CSRF

Parametrii de redirecționare

După o instalare reușită, Stripe redirecționează utilizatorul către redirect_uri cu următorii parametri în adresă:

Parametru	Descriere
`user_id`	ID-ul de utilizator Stripe al contului care instalează aplicația
`account_id`	ID-ul contului Stripe (de exemplu `acct_xxxxx`)
`state`	Valoarea `state` trimisă de tine (pentru verificarea CSRF)
`install_signature`	Semnătura HMAC prin care verifici că instalarea este legitimă

Exemplu de URL de redirecționare:

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

Protecție CSRF

Folosește întotdeauna parametrul state ca să previi atacurile de tip 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');
};

Verificarea semnăturii

Verifică install_signature folosind secretul de semnare al aplicației tale:

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

Folosește întotdeauna crypto.timingSafeEqual pentru compararea semnăturilor, ca să previi atacurile bazate pe timp. Nu folosi niciodată o simplă egalitate de șiruri (===).

Secretul de semnare

Secretul de semnare al aplicației tale este disponibil în panoul Stripe, în setările aplicației. Îl folosești ca:

Să verifici semnăturile de instalare din apelurile de redirecționare
Să validezi payloadurile webhook trimise de Stripe
Să autentifici cererile dintre backendul tău și Stripe

Păstrează secretul de semnare în siguranță:

# Set as environment variable
export STRIPE_APP_SIGNING_SECRET="whsec_xxxxx"

Nu scrie niciodată secretele de semnare direct în codul sursă și nu le urca în sistemul de versionare.

Linkuri profunde

Linkurile profunde duc utilizatorii direct într-o anumită vizualizare din aplicația ta Stripe instalată. Folosește-le ca să îi trimiți din comunicări externe (e-mailuri, notificări, pagini de asistență) direct în contextul potrivit din aplicație.

Formatul URL-ului pentru linkuri profunde

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

Componentă	Descriere	Exemplu
`MODE`	`live` sau `test`	`live`
`acct_ID`	ID-ul contului Stripe vizat	`acct_1234567890`
`PAGE`	Calea paginii din panou	`customers/cus_xxxxx`
`APP_ID`	ID-ul aplicației tale	`com.tajo.brevo-integration`
`TARGET`	`drawer` sau `modal`	`drawer`
`VIEWPORT_ID`	Viewportul care se deschide	`stripe.dashboard.customer.detail`

Țintă	Comportament	Când o folosești
`drawer`	Deschide aplicația în panoul lateral (drawer)	Interacțiunea implicită cu aplicația, context alături de pagină
`modal`	Deschide aplicația într-o fereastră modală pe tot ecranul	Fluxuri care cer concentrare, inițiere, formulare complexe

Exemple de linkuri profunde

Deschide vizualizarea detaliilor unui client în drawer

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

Deschide setările într-o fereastră modală

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

Deschide fluxul de inițiere

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

Deschide detaliile unei plăți în modul de test

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

Generarea programatică a linkurilor profunde

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

Folosirea linkurilor profunde în comunicări

Linkurile profunde sunt utile mai ales în:

Notificări prin e-mail: „Vezi starea sincronizării cu Brevo pentru acest client“
Răspunsuri de asistență: „Dă clic aici ca să îți verifici setările integrării“
E-mailuri de inițiere: „Finalizează configurarea Brevo“
Alerte de eroare: „Verifică problema de sincronizare pentru clientul 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>

Combinarea linkurilor de instalare cu linkurile profunde

Pentru cea mai bună experiență de inițiere, combină linkurile de instalare cu linkuri profunde afișate după instalare:

Utilizatorul dă clic pe un link de instalare de pe site-ul tău sau dintr-un e-mail
Utilizatorul instalează aplicația și este redirecționat către URL-ul tău de callback
Callbackul tău procesează instalarea și îl redirecționează pe utilizator către un link profund care deschide viewportul de inițiere

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

Testează întotdeauna linkurile de instalare și linkurile profunde atât în modul live, cât și în modul test, ca să te asiguri că funcționează corect în toate mediile.