Zaprosite za zgodnji dostop

Vnesite ime ter e-poštni naslov ali telefonsko številko. Poslali vam bomo podrobnosti o dostopu do platforme Tajo.

Na tej strani

Namestitvene in globoke povezave

Namestitvene povezave omogočajo distribucijo aplikacije Stripe App zunaj tržnice, globoke povezave pa uporabnika pripeljejo naravnost do določenega pogleda v nameščeni aplikaciji. Oboje je bistveno za tekoče uvajanje in integracijske poteke.

Namestitvene povezave

Namestitvene povezave so neposredni URL, s katerim lahko trgovci namestijo vašo aplikacijo. Ko uporabnik klikne namestitveno povezavo, Stripe izvede potek namestitve in ga nato preusmeri nazaj na URI, ki ste ga določili.

Predpogoji

Preden začnete uporabljati namestitvene povezave, v manifestu aplikacije nastavite allowed_redirect_uris:

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

Oblika namestitvene povezave

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

Parameter	Obvezno	Opis
`client_id`	Da	ID vaše aplikacije (npr. `com.tajo.brevo-integration`)
`redirect_uri`	Da	Ujemati se mora z enim od vaših `allowed_redirect_uris`
`state`	Priporočeno	Naključni niz za zaščito pred CSRF

Parametri preusmeritve

Po uspešni namestitvi Stripe uporabnika preusmeri na vaš redirect_uri s temi poizvedbenimi parametri:

Parameter	Opis
`user_id`	ID uporabnika Stripe za račun, ki izvaja namestitev
`account_id`	ID računa Stripe (npr. `acct_xxxxx`)
`state`	Vrednost `state`, ki ste jo posredovali (za preverjanje CSRF)
`install_signature`	Podpis HMAC, s katerim preverite, ali je namestitev legitimna

Primer URL-ja za preusmeritev:

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

Zaščita pred CSRF

Vedno uporabite parameter state, da preprečite napade s ponarejanjem zahtev med spletnimi mesti (CSRF):

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

Preverjanje podpisa

Podpis install_signature preverite s skrivnostjo za podpisovanje svoje aplikacije:

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

Za primerjavo podpisov vedno uporabite crypto.timingSafeEqual, da preprečite časovne napade. Nikoli ne uporabljajte preprostega preverjanja enakosti nizov (===).

Skrivnost za podpisovanje

Skrivnost za podpisovanje vaše aplikacije je na voljo v nadzorni plošči Stripe med nastavitvami aplikacije. Uporabite jo za:

Preverjanje namestitvenih podpisov iz povratnih klicev ob preusmeritvi
Potrjevanje vsebine webhookov iz Stripa
Avtentikacijo zahtev med vašim zaledjem in Stripom

Skrivnost za podpisovanje shranite varno:

# Set as environment variable
export STRIPE_APP_SIGNING_SECRET="whsec_xxxxx"

Skrivnosti za podpisovanje nikoli ne zapišite neposredno v izvorno kodo in je ne shranite v sistem za nadzor različic.

Globoke povezave

Globoke povezave uporabnika pripeljejo naravnost do določenega pogleda v nameščeni aplikaciji Stripe App. Uporabite jih, da uporabnika iz zunanjih sporočil (e-pošte, obvestil, strani za podporo) pripeljete do ustreznega konteksta v aplikaciji.

Oblika URL-ja globoke povezave

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

Komponenta	Opis	Primer
`MODE`	`live` ali `test`	`live`
`acct_ID`	ID ciljnega računa Stripe	`acct_1234567890`
`PAGE`	Pot do strani v nadzorni plošči	`customers/cus_xxxxx`
`APP_ID`	ID vaše aplikacije	`com.tajo.brevo-integration`
`TARGET`	`drawer` ali `modal`	`drawer`
`VIEWPORT_ID`	Viewport, ki naj se odpre	`stripe.dashboard.customer.detail`

Cilj	Vedenje	Primer uporabe
`drawer`	Aplikacijo odpre v stranski plošči (drawer)	Privzeta interakcija z aplikacijo, kontekst ob strani
`modal`	Aplikacijo odpre v celozaslonskem modalnem oknu	Osredotočeni poteki dela, uvajanje, zahtevnejši obrazci

Primeri globokih povezav

Odpiranje podrobnosti o stranki v stranski plošči

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

Odpiranje nastavitev v modalnem oknu

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

Odpiranje poteka uvajanja

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

Odpiranje podrobnosti o plačilu v testnem načinu

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

Programsko ustvarjanje globokih povezav

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

Uporaba globokih povezav v komunikaciji

Globoke povezave so še posebej uporabne v teh primerih:

E-poštna obvestila: „Oglejte si stanje sinhronizacije z Brevom za to stranko”
Odgovori podpore: „Kliknite tukaj in preverite nastavitve integracije”
E-pošta ob uvajanju: „Dokončajte nastavitev Breva”
Opozorila o napakah: „Preglejte težavo pri sinhronizaciji za stranko 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>

Kombiniranje namestitvenih in globokih povezav

Za najboljšo izkušnjo uvajanja namestitvene povezave združite z globokimi povezavami po namestitvi:

Uporabnik na vašem spletnem mestu ali v e-pošti klikne namestitveno povezavo
Uporabnik namesti aplikacijo in je preusmerjen na vaš URL za povratni klic
Vaš povratni klic obdela namestitev in uporabnika preusmeri na globoko povezavo, ki odpre viewport za uvajanje

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

Namestitvene in globoke povezave vedno preizkusite tako v načinu live kot v načinu test, da bodo pravilno delovale v vseh okoljih.