On this page

Installationslänkar och djuplänkar

Installationslänkar låter dig distribuera din Stripe-app utanför marknadsplatsen, medan djuplänkar navigerar användare direkt till specifika vyer i din installerade app. Båda är viktiga för smidig onboarding och integrationsflöden.

Installationslänkar

Installationslänkar tillhandahåller en direkt URL som handlare kan använda för att installera din app. När en användare klickar på en installationslänk hanterar Stripe installationsflödet och omdirigerar sedan tillbaka till din angivna URI.

Förutsättningar

Konfigurera allowed_redirect_uris i ditt appmanifest innan du använder installationslänkar:

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

Format för installationslänk

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

Parameter	Obligatorisk	Beskrivning
`client_id`	Ja	Ditt app-ID (t.ex. `com.tajo.brevo-integration`)
`redirect_uri`	Ja	Måste matcha en av dina `allowed_redirect_uris`
`state`	Rekommenderas	Slumpmässig sträng för CSRF-skydd

Omdirigeringsparametrar

Efter en lyckad installation omdirigerar Stripe användaren till din redirect_uri med dessa frågeparametrar:

Parameter	Beskrivning
`user_id`	Stripe-användar-ID för det installerande kontot
`account_id`	Stripe-konto-ID (t.ex. `acct_xxxxx`)
`state`	Det `state`-värde du angav (för CSRF-verifiering)
`install_signature`	HMAC-signatur för att verifiera att installationen är legitim

Exempel på omdirigerings-URL:

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

CSRF-skydd

Använd alltid state-parametern för att förhindra cross-site request forgery-attacker:

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

Signaturverifiering

Verifiera install_signature med din apps signeringshemlighet:

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

Använd alltid crypto.timingSafeEqual för signatursignaturjämförelse för att förhindra timing-attacker. Använd aldrig enkel stränglikhet (===).

Signeringshemlighet

Din apps signeringshemlighet finns i Stripe Dashboard under appens inställningar. Använd den för att:

Verifiera installationssignaturer från omdirigeringsåterrop
Validera webhook-nyttolaster från Stripe
Autentisera förfrågningar mellan din backend och Stripe

Lagra signeringshemligheten på ett säkert sätt:

# Set as environment variable
export STRIPE_APP_SIGNING_SECRET="whsec_xxxxx"

Hårdkoda aldrig signeringshemligheter i din källkod eller commit:a dem till versionshantering.

Djuplänkar

Djuplänkar navigerar användare direkt till en specifik vy i din installerade Stripe-app. Använd dem för att dirigera användare från extern kommunikation (e-post, notifikationer, supportsidor) till relevant appkontext.

URL-format för djuplänk

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

Komponent	Beskrivning	Exempel
`MODE`	`live` eller `test`	`live`
`acct_ID`	Mål-Stripe-konto-ID	`acct_1234567890`
`PAGE`	Dashboardsökvägssida	`customers/cus_xxxxx`
`APP_ID`	Ditt app-ID	`com.tajo.brevo-integration`
`TARGET`	`drawer` eller `modal`	`drawer`
`VIEWPORT_ID`	Viewporten som ska öppnas	`stripe.dashboard.customer.detail`

Mål	Beteende	Användningsfall
`drawer`	Öppnar appen i sidopanelen (drawer)	Standard appinteraktion, kontext vid sidan av sidan
`modal`	Öppnar appen i en helskärmsmodal-overlay	Fokuserade arbetsflöden, onboarding, komplexa formulär

Djuplänksexempel

Öppna kunddetaljvy i drawer

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

Öppna onboardingflöde

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

Öppna betalningsdetaljvy i testläge

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

Generera djuplänkar programmatiskt

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

Använda djuplänkar i kommunikation

Djuplänkar är särskilt användbara i:

E-postnotifikationer: “Visa Brevo-synkroniseringsstatus för den här kunden”
Supportsvar: “Klicka här för att kontrollera dina integrationsinställningar”
Onboarding-e-post: “Slutför din Brevo-konfiguration”
Felalertar: “Granska synkroniseringsproblemet för kund 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>

Kombinera installationslänkar och djuplänkar

För bästa onboardingupplevelse, kombinera installationslänkar med djuplänkar efter installation:

Användaren klickar på en installationslänk från din webbplats eller e-post
Användaren installerar appen och omdirigeras till din callback-URL
Din callback behandlar installationen och omdirigerar användaren till en djuplänk som öppnar onboarding-viewporten

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

Testa alltid installationslänkar och djuplänkar i både live- och testläge för att säkerställa att de fungerar korrekt i alla miljöer.

Installationslänkar och djuplänkar