On this page

Installations- og dybe links

Installationslinks lader dig distribuere din Stripe App uden for marketplace, mens dybe links navigerer brugere direkte til specifikke visninger i din installerede app. Begge er essentielle for glidende onboarding- og integrationsflows.

Installationslinks

Installationslinks tilbyder en direkte URL som sælgere kan bruge til at installere din app. Når en bruger klikker på et installationslink, håndterer Stripe installationsflowet og omdirigerer derefter tilbage til din angivne URI.

Forudsætninger

Inden du bruger installationslinks, konfigurer allowed_redirect_uris i dit app-manifest:

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

Installationslink-format

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

Parameter	Påkrævet	Beskrivelse
`client_id`	Ja	Dit app-ID (f.eks. `com.tajo.brevo-integration`)
`redirect_uri`	Ja	Skal matche en af dine `allowed_redirect_uris`
`state`	Anbefalet	Tilfældig streng til CSRF-beskyttelse

Redirect-parametre

Efter en vellykket installation omdirigerer Stripe brugeren til din redirect_uri med disse forespørgselsparametre:

Parameter	Beskrivelse
`user_id`	Stripe-bruger-ID’et for den installerende konto
`account_id`	Stripe-konto-ID’et (f.eks. `acct_xxxxx`)
`state`	`state`-værdien du opgav (til CSRF-verificering)
`install_signature`	HMAC-signatur til at verificere installationen er legitim

CSRF-beskyttelse

Brug altid state-parameteren til at forhindre cross-site request forgery-angreb:

import crypto from 'crypto';

const generateInstallLink = (req, res) => {
  const state = crypto.randomBytes(32).toString('hex');
  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());
};

const handleInstallCallback = (req, res) => {
  const { state, user_id, account_id, install_signature } = req.query;

  if (state !== req.session.stripeInstallState) {
    return res.status(403).json({ error: 'Invalid state parameter' });
  }

  delete req.session.stripeInstallState;

  if (!verifyInstallSignature(install_signature, account_id)) {
    return res.status(403).json({ error: 'Invalid install signature' });
  }

  await processInstallation(user_id, account_id);
  res.redirect('/dashboard/stripe-connected');
};

Signaturverificering

Verificer install_signature med din apps signeringshemmelighed:

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

Brug altid crypto.timingSafeEqual til signatursammenligning for at forhindre timing-angreb. Brug aldrig simpel strengsammenligning (===).

Dybe links

Dybe links navigerer brugere direkte til en specifik visning i din installerede Stripe App. Brug dem til at dirigere brugere fra eksterne kommunikationer (emails, notifikationer, supportsider) til den relevante app-kontekst.

Dybt link-URL-format

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

Komponent	Beskrivelse	Eksempel
`MODE`	`live` eller `test`	`live`
`acct_ID`	Mål-Stripe-konto-ID	`acct_1234567890`
`PAGE`	Dashboard-sidesti	`customers/cus_xxxxx`
`APP_ID`	Din apps ID	`com.tajo.brevo-integration`
`TARGET`	`drawer` eller `modal`	`drawer`
`VIEWPORT_ID`	Det viewport der åbnes	`stripe.dashboard.customer.detail`

Mål	Adfærd	Brugsscenarie
`drawer`	Åbner appen i sidepanelet (skuffen)	Standard app-interaktion, kontekst ved siden af siden
`modal`	Åbner appen i en fuldskærmsmodal overlay	Fokuserede workflows, onboarding, komplekse formularer

Dybe link-eksempler

Åbn kundedetaljevisning 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

Åbn onboarding-flow

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

Generering af dybe links 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()}`;
};

const customerLink = generateDeepLink({
  accountId: 'acct_xxxxx',
  page: 'customers/cus_xxxxx',
  viewport: 'stripe.dashboard.customer.detail',
});

const settingsLink = generateDeepLink({
  accountId: 'acct_xxxxx',
  page: 'settings',
  viewport: 'stripe.dashboard.settings',
  target: 'modal',
});

Brug af dybe links i kommunikationer

Dybe links er særligt nyttige i:

Emailnotifikationer: “Se Brevo-synkstatus for denne kunde”
Supportsvar: “Klik her for at kontrollere dine integrationsindstillinger”
Onboardingemails: “Fuldfør din Brevo-opsætning”
Fejladvarsler: “Gennemgå synkproblemet for kunde X”

Kombination af installationslinks og dybe links

For den bedste onboardingoplevelse, kombiner installationslinks med post-installations-dybe links:

Bruger klikker på et installationslink fra dit website eller din email
Bruger installerer appen og omdirigeres til din callback-URL
Din callback behandler installationen og omdirigerer brugeren til et dybt link der åbner onboarding-viewportet

const handleInstallCallback = async (req, res) => {
  const { account_id, install_signature, state } = req.query;

  // Verificer state og signatur
  await processInstallation(account_id);

  const onboardingLink = generateDeepLink({
    accountId: account_id,
    page: 'dashboard',
    viewport: 'stripe.dashboard.onboarding',
    target: 'modal',
  });

  res.redirect(onboardingLink);
};

Tip

Test altid installationslinks og dybe links i både live- og testmodus for at sikre de fungerer korrekt i alle miljøer.