Zatražite rani pristup

Unesite ime i imejl adresu ili broj telefona. Poslaćemo vam detalje o pristupu platformi Tajo.

Na ovoj stranici

Instalacioni i duboki linkovi

Instalacioni linkovi vam omogućavaju da distribuirate svoju Stripe aplikaciju izvan marketplace platforme, dok duboki linkovi vode korisnike direktno do određenih prikaza unutar instalirane aplikacije. Oba su ključna za gladak proces uvođenja i integracije.

Instalacioni linkovi

Instalacioni linkovi pružaju direktnu URL adresu preko koje trgovci mogu da instaliraju vašu aplikaciju. Kada korisnik klikne na instalacioni link, Stripe sprovodi proces instalacije i zatim ga preusmerava nazad na URI koji ste naveli.

Preduslovi

Pre korišćenja instalacionih linkova, podesite allowed_redirect_uris u manifestu aplikacije:

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

Format instalacionog linka

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 (na primer `com.tajo.brevo-integration`)
`redirect_uri`	Da	Mora da odgovara jednoj od vrednosti u `allowed_redirect_uris`
`state`	Preporučeno	Nasumičan string za zaštitu od CSRF napada

Parametri preusmeravanja

Nakon uspešne instalacije, Stripe preusmerava korisnika na vaš redirect_uri sa sledećim parametrima upita:

Parametar	Opis
`user_id`	Stripe ID korisnika naloga koji instalira aplikaciju
`account_id`	Stripe ID naloga (na primer `acct_xxxxx`)
`state`	Vrednost `state` koju ste prosledili (za CSRF proveru)
`install_signature`	HMAC potpis kojim se potvrđuje da je instalacija legitimna

Primer URL adrese za preusmeravanje:

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

Zaštita od CSRF napada

Uvek koristite parametar state da biste sprečili napade tipa 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');
};

Provera potpisa

Proverite install_signature pomoću tajnog ključa za potpisivanje vaše 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 poređenje potpisa uvek koristite crypto.timingSafeEqual kako biste sprečili napade zasnovane na merenju vremena. Nikada ne koristite običnu proveru jednakosti stringova (===).

Tajni ključ za potpisivanje

Tajni ključ za potpisivanje vaše aplikacije dostupan je u Stripe Dashboardu, u podešavanjima aplikacije. Koristite ga da biste:

proverili potpise instalacije iz povratnih poziva za preusmeravanje
potvrdili validnost webhook sadržaja koji stiže sa Stripe-a
autentifikovali zahteve između vašeg pozadinskog sistema i Stripe-a

Čuvajte tajni ključ za potpisivanje na bezbedan način:

# Set as environment variable
export STRIPE_APP_SIGNING_SECRET="whsec_xxxxx"

Nikada nemojte upisivati tajne ključeve za potpisivanje direktno u izvorni kod niti ih slati u sistem za kontrolu verzija.

Duboki linkovi

Duboki linkovi vode korisnike direktno do određenog prikaza unutar instalirane Stripe aplikacije. Koristite ih da biste korisnike iz spoljne komunikacije (imejlova, obaveštenja, stranica podrške) doveli u odgovarajući kontekst aplikacije.

Format URL adrese dubokog linka

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

Komponenta	Opis	Primer
`MODE`	`live` ili `test`	`live`
`acct_ID`	ID ciljnog Stripe naloga	`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 treba otvoriti	`stripe.dashboard.customer.detail`

Cilj	Ponašanje	Primena
`drawer`	Otvara aplikaciju u bočnom panelu (fioci)	Podrazumevana interakcija sa aplikacijom, kontekst uz samu stranicu
`modal`	Otvara aplikaciju u modalnom prekrivaču preko celog ekrana	Fokusirani tokovi rada, uvođenje, složeni formulari

Primeri dubokih linkova

Otvaranje prikaza detalja o kupcu u fioci

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

Otvaranje podešavanja u modalnom prozoru

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

Otvaranje toka uvođenja

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

Otvaranje prikaza detalja o plaćanju u test režimu

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

Programsko generisanje dubokih linkova

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šćenje dubokih linkova u komunikaciji

Duboki linkovi su naročito korisni u sledećim situacijama:

Imejl obaveštenja: „Pogledajte status Brevo sinhronizacije za ovog kupca”
Odgovori podrške: „Kliknite ovde da biste proverili podešavanja integracije”
Imejlovi za uvođenje: „Dovršite podešavanje Breva”
Upozorenja o greškama: „Pregledajte problem sa sinhronizacijom 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>

Kombinovanje instalacionih i dubokih linkova

Za najbolje iskustvo uvođenja, kombinujte instalacione linkove sa dubokim linkovima nakon instalacije:

Korisnik klikne na instalacioni link na vašem sajtu ili u imejlu
Korisnik instalira aplikaciju i biva preusmeren na vašu povratnu URL adresu
Vaš povratni poziv obrađuje instalaciju i preusmerava korisnika na duboki link koji 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

Uvek testirajte instalacione i duboke linkove i u live i u test režimu kako biste bili sigurni da ispravno rade u svim okruženjima.