Kérj korai hozzáférést

Add meg a keresztnevedet, valamint egy e-mail-címet vagy telefonszámot. Hamarosan elküldjük a Tajo eléréséhez szükséges információkat.

Ezen az oldalon

Telepítési és mély hivatkozások

A telepítési hivatkozásokkal a marketplace-en kívül is terjesztheted a Stripe Appodat, a mély hivatkozások pedig közvetlenül a telepített appod egy adott nézetéhez viszik a felhasználót. Mindkettő elengedhetetlen a gördülékeny bevezetéshez és az integrációs folyamatokhoz.

Telepítési hivatkozások

A telepítési hivatkozás egy közvetlen URL, amellyel a kereskedők telepíthetik az appodat. Amikor a felhasználó rákattint, a Stripe lebonyolítja a telepítési folyamatot, majd visszairányít az általad megadott URI-ra.

Előfeltételek

Mielőtt telepítési hivatkozásokat használnál, állítsd be az allowed_redirect_uris mezőt az app manifesztjében:

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

A telepítési hivatkozás formátuma

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

Paraméter	Kötelező	Leírás
`client_id`	Igen	Az appod azonosítója (például `com.tajo.brevo-integration`)
`redirect_uri`	Igen	Meg kell egyeznie az `allowed_redirect_uris` egyik elemével
`state`	Ajánlott	Véletlenszerű karakterlánc a CSRF elleni védelemhez

Átirányítási paraméterek

Sikeres telepítés után a Stripe a redirect_uri címre irányítja a felhasználót, a következő lekérdezési paraméterekkel:

Paraméter	Leírás
`user_id`	A telepítést végző fiók Stripe felhasználóazonosítója
`account_id`	A Stripe fiókazonosító (például `acct_xxxxx`)
`state`	Az általad megadott `state` érték (a CSRF-ellenőrzéshez)
`install_signature`	HMAC aláírás annak igazolására, hogy a telepítés valódi

Példa átirányítási URL:

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

CSRF elleni védelem

Mindig használd a state paramétert a cross-site request forgery támadások megelőzésére:

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

Aláírás-ellenőrzés

Ellenőrizd az install_signature értékét az appod aláírási titkával:

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

Az aláírások összehasonlításához mindig a crypto.timingSafeEqual függvényt használd, így véded ki az időzítéses támadásokat. Soha ne használj egyszerű karakterlánc-egyenlőséget (===).

Aláírási titok

Az appod aláírási titka a Stripe irányítópultján, az app beállításai között érhető el. A következőkre használd:

Az átirányítási visszahívásokból érkező telepítési aláírások ellenőrzése
A Stripe-tól érkező webhook-tartalmak érvényesítése
A backended és a Stripe közötti kérések hitelesítése

Az aláírási titkot biztonságosan tárold:

# Set as environment variable
export STRIPE_APP_SIGNING_SECRET="whsec_xxxxx"

Soha ne égesd bele az aláírási titkokat a forráskódba, és ne kommitold őket verziókövetőbe.

Mély hivatkozások

A mély hivatkozások közvetlenül a telepített Stripe Appod egy adott nézetéhez viszik a felhasználót. Használd őket arra, hogy külső csatornákról (e-mailek, értesítések, támogatási oldalak) a megfelelő app-kontextusba juttasd a felhasználókat.

A mély hivatkozás URL formátuma

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

Elem	Leírás	Példa
`MODE`	`live` vagy `test`	`live`
`acct_ID`	A cél Stripe fiókazonosító	`acct_1234567890`
`PAGE`	Az irányítópult oldalának útvonala	`customers/cus_xxxxx`
`APP_ID`	Az appod azonosítója	`com.tajo.brevo-integration`
`TARGET`	`drawer` vagy `modal`	`drawer`
`VIEWPORT_ID`	A megnyitandó nézet	`stripe.dashboard.customer.detail`

Cél	Viselkedés	Mikor használd
`drawer`	Az appot az oldalsó panelen nyitja meg	Alapértelmezett app-használat, kontextus az oldal mellett
`modal`	Az appot teljes képernyős modális rétegben nyitja meg	Fókuszált folyamatok, bevezetés, összetett űrlapok

Példák mély hivatkozásokra

Vásárló részletes nézetének megnyitása az oldalsó panelen

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

Beállítások megnyitása modális ablakban

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

Bevezetési folyamat megnyitása

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

Fizetés részletes nézetének megnyitása teszt módban

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

Mély hivatkozások generálása programból

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

Mély hivatkozások használata a kommunikációban

A mély hivatkozások különösen hasznosak a következőkben:

E-mail-értesítések: „Nézd meg a vásárló Brevo szinkronizálási állapotát”
Támogatási válaszok: „Kattints ide az integrációs beállítások ellenőrzéséhez”
Bevezető e-mailek: „Fejezd be a Brevo beállítását”
Hibariasztások: „Nézd át az X vásárlónál jelentkező szinkronizálási hibát”

<!-- 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>