Be om tidlig tilgang

Skriv inn fornavnet ditt og en e-postadresse eller et telefonnummer. Vi kontakter deg med informasjon om tilgang til Tajo.

På denne siden

Installasjonslenker og dype lenker

Installasjonslenker lar deg distribuere Stripe-appen din utenfor marketplace, mens dype lenker tar brukerne rett til bestemte visninger i den installerte appen. Begge deler er avgjørende for smidig onboarding og gode integrasjonsflyter.

Installasjonslenker

Installasjonslenker gir en direkte URL som selgerne kan bruke for å installere appen din. Når en bruker klikker på en installasjonslenke, håndterer Stripe installasjonsflyten og sender deretter brukeren tilbake til URI-en du har oppgitt.

Forutsetninger

Før du tar i bruk installasjonslenker, må du konfigurere allowed_redirect_uris i app-manifestet ditt:

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

Format for installasjonslenke

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

Parameter	Påkrevd	Beskrivelse
`client_id`	Ja	App-ID-en din (for eksempel `com.tajo.brevo-integration`)
`redirect_uri`	Ja	Må samsvare med en av verdiene i `allowed_redirect_uris`
`state`	Anbefalt	Tilfeldig streng for CSRF-beskyttelse

Parametere ved omdirigering

Etter en vellykket installasjon sender Stripe brukeren til redirect_uri med disse spørringsparameterne:

Parameter	Beskrivelse
`user_id`	Stripe-bruker-ID-en til kontoen som installerer
`account_id`	Stripe-konto-ID-en (for eksempel `acct_xxxxx`)
`state`	Verdien du oppga i `state` (til CSRF-verifisering)
`install_signature`	HMAC-signatur som bekrefter at installasjonen er legitim

Eksempel på omdirigerings-URL:

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

CSRF-beskyttelse

Bruk alltid state-parameteren for å hindre angrep med forfalskede forespørsler på tvers av nettsteder:

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

Verifisering av signatur

Verifiser install_signature med appens signeringshemmelighet:

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

Bruk alltid crypto.timingSafeEqual når du sammenligner signaturer, slik at du unngår timing-angrep. Bruk aldri enkel strengsammenligning (===).

Signeringshemmelighet

Appens signeringshemmelighet finner du i Stripe Dashboard under innstillingene for appen. Bruk den til å:

Verifisere installasjonssignaturer fra omdirigeringer tilbake til deg
Validere webhook-nyttelast fra Stripe
Autentisere forespørsler mellom backend-en din og Stripe

Oppbevar signeringshemmeligheten trygt:

# Set as environment variable
export STRIPE_APP_SIGNING_SECRET="whsec_xxxxx"

Legg aldri signeringshemmeligheter rett inn i kildekoden, og sjekk dem aldri inn i versjonskontroll.

Dype lenker

Dype lenker tar brukerne rett til en bestemt visning i den installerte Stripe-appen din. Bruk dem til å lede brukerne fra ekstern kommunikasjon (e-post, varsler, supportsider) til riktig sted i appen.

Format for URL til dyp lenke

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

Komponent	Beskrivelse	Eksempel
`MODE`	`live` eller `test`	`live`
`acct_ID`	Stripe-konto-ID-en du sikter mot	`acct_1234567890`
`PAGE`	Sti til siden i dashboard	`customers/cus_xxxxx`
`APP_ID`	ID-en til appen din	`com.tajo.brevo-integration`
`TARGET`	`drawer` eller `modal`	`drawer`
`VIEWPORT_ID`	Visningen som skal åpnes	`stripe.dashboard.customer.detail`

Mål	Oppførsel	Bruksområde
`drawer`	Åpner appen i sidepanelet (skuffen)	Vanlig bruk av appen, kontekst ved siden av siden
`modal`	Åpner appen i et modalvindu over hele skjermen	Konsentrerte arbeidsflyter, onboarding, sammensatte skjemaer

Eksempler på dype lenker

Åpne kundedetaljvisningen i skuffen

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

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

Åpne onboarding-flyten

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

Åpne betalingsdetaljvisningen i testmodus

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

Generere dype lenker programmatisk

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

Bruk av dype lenker i kommunikasjon

Dype lenker er spesielt nyttige i:

Varsler på e-post: «Se synkroniseringsstatusen mot Brevo for denne kunden»
Svar fra support: «Klikk her for å sjekke integrasjonsinnstillingene dine»
Onboarding-e-poster: «Fullfør Brevo-oppsettet ditt»
Feilvarsler: «Se gjennom synkroniseringsproblemet for kunde 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>

Kombinere installasjonslenker og dype lenker

For den beste onboarding-opplevelsen kombinerer du installasjonslenker med dype lenker etter installasjon:

Brukeren klikker på en installasjonslenke fra nettstedet ditt eller en e-post
Brukeren installerer appen og sendes videre til callback-URL-en din
Callback-en din behandler installasjonen og sender brukeren videre til en dyp lenke som åpner onboarding-visningen

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

Test alltid installasjonslenker og dype lenker i både live- og testmodus, slik at du vet at de fungerer i alle miljøer.