Zatražite rani pristup

Unesite ime te adresu e-pošte ili telefonski broj. Poslat ćemo vam pojedinosti o pristupu platformi Tajo.

Na ovoj stranici

Poveznice za instalaciju i duboke poveznice

Poveznice za instalaciju omogućuju vam distribuciju vaše Stripe aplikacije izvan tržnice, dok duboke poveznice korisnike vode izravno na određene prikaze unutar instalirane aplikacije. Oboje je ključno za neometano uvođenje i tijekove integracije.

Poveznice za instalaciju

Poveznice za instalaciju daju izravan URL kojim trgovci mogu instalirati vašu aplikaciju. Kada korisnik klikne poveznicu za instalaciju, Stripe provodi tijek instalacije i zatim ga preusmjerava natrag na URI koji ste naveli.

Preduvjeti

Prije korištenja poveznica za instalaciju konfigurirajte allowed_redirect_uris u manifestu svoje aplikacije:

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

Format poveznice za instalaciju

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

Parametar	Obavezno	Opis
`client_id`	Da	ID vaše aplikacije (npr. `com.tajo.brevo-integration`)
`redirect_uri`	Da	Mora odgovarati jednom od vaših `allowed_redirect_uris`
`state`	Preporučeno	Nasumičan niz znakova za zaštitu od CSRF-a

Parametri preusmjeravanja

Nakon uspješne instalacije Stripe preusmjerava korisnika na vaš redirect_uri s ovim parametrima upita:

Parametar	Opis
`user_id`	Stripe ID korisnika računa koji provodi instalaciju
`account_id`	ID Stripe računa (npr. `acct_xxxxx`)
`state`	Vrijednost `state` koju ste naveli (za provjeru CSRF-a)
`install_signature`	HMAC potpis kojim se provjerava je li instalacija legitimna

Primjer URL-a preusmjeravanja:

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

Zaštita od CSRF-a

Uvijek koristite parametar state kako biste spriječili napade krivotvorenja zahtjeva između web-mjesta:

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

Provjera potpisa

Provjerite install_signature pomoću tajne za potpisivanje 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 usporedbu potpisa uvijek koristite crypto.timingSafeEqual kako biste spriječili vremenske napade. Nikada nemojte koristiti jednostavnu usporedbu nizova znakova (===).

Tajna za potpisivanje

Tajna za potpisivanje vaše aplikacije dostupna je u Stripe Dashboardu, u postavkama aplikacije. Koristite je za sljedeće:

Provjeru potpisa instalacije iz povratnih poziva preusmjeravanja
Provjeru valjanosti webhook sadržaja koji dolazi iz Stripea
Autentifikaciju zahtjeva između vašeg poslužiteljskog dijela i Stripea

Tajnu za potpisivanje pohranite na siguran način:

# Set as environment variable
export STRIPE_APP_SIGNING_SECRET="whsec_xxxxx"

Tajne za potpisivanje nikada nemojte ugrađivati izravno u izvorni kod niti ih spremati u sustav za kontrolu verzija.

Duboke poveznice

Duboke poveznice vode korisnike izravno na određeni prikaz unutar vaše instalirane Stripe aplikacije. Koristite ih da biste korisnike iz vanjske komunikacije (e-pošta, obavijesti, stranice podrške) doveli u odgovarajući kontekst aplikacije.

Format URL-a duboke poveznice

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

Komponenta	Opis	Primjer
`MODE`	`live` ili `test`	`live`
`acct_ID`	ID ciljanog Stripe računa	`acct_1234567890`
`PAGE`	Putanja stranice u Dashboardu	`customers/cus_xxxxx`
`APP_ID`	ID vaše aplikacije	`com.tajo.brevo-integration`
`TARGET`	`drawer` ili `modal`	`drawer`
`VIEWPORT_ID`	Viewport koji se otvara	`stripe.dashboard.customer.detail`

Cilj	Ponašanje	Primjena
`drawer`	Otvara aplikaciju u bočnoj ploči (drawer)	Zadana interakcija s aplikacijom, kontekst uz samu stranicu
`modal`	Otvara aplikaciju u modalnom prekrivaču preko cijelog zaslona	Fokusirani tijekovi rada, uvođenje, složeni obrasci

Primjeri dubokih poveznica

Otvaranje prikaza detalja o kupcu u bočnoj ploči

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

Otvaranje postavki u modalnom prozoru

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

Otvaranje tijeka uvođenja

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

Otvaranje prikaza detalja plaćanja u testnom načinu rada

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

Programsko generiranje dubokih poveznica

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

Korištenje dubokih poveznica u komunikaciji

Duboke poveznice osobito su korisne u sljedećim slučajevima:

Obavijesti e-poštom: „Pogledajte status sinkronizacije s Brevom za ovog kupca“
Odgovori podrške: „Kliknite ovdje da biste provjerili postavke svoje integracije“
E-poruke za uvođenje: „Dovršite postavljanje Breva“
Upozorenja o pogreškama: „Pregledajte problem sa sinkronizacijom za kupca 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 poveznica za instalaciju i dubokih poveznica

Za najbolje iskustvo uvođenja kombinirajte poveznice za instalaciju s dubokim poveznicama nakon instalacije:

Korisnik klikne poveznicu za instalaciju na vašem web-mjestu ili u e-poruci
Korisnik instalira aplikaciju i preusmjerava se na vaš URL povratnog poziva
Vaš povratni poziv obrađuje instalaciju i preusmjerava korisnika na duboku poveznicu koja otvara viewport za uvođenje

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

Poveznice za instalaciju i duboke poveznice uvijek testirajte i u načinu rada uživo i u testnom načinu rada kako biste bili sigurni da ispravno rade u svim okruženjima.