Ζητήστε πρώιμη πρόσβαση

Συμπληρώστε το όνομά σας και ένα email ή έναν αριθμό τηλεφώνου. Θα σας στείλουμε πληροφορίες για την πρόσβαση στο Tajo.

Σε αυτή τη σελίδα

Σύνδεσμοι εγκατάστασης και deep links

Οι σύνδεσμοι εγκατάστασης σάς επιτρέπουν να διανέμετε το Stripe App σας εκτός του marketplace, ενώ τα deep links οδηγούν τους χρήστες απευθείας σε συγκεκριμένες προβολές μέσα στην εγκατεστημένη εφαρμογή σας. Και τα δύο είναι απαραίτητα για ομαλές ροές onboarding (ένταξης χρηστών) και ενσωμάτωσης.

Σύνδεσμοι εγκατάστασης

Οι σύνδεσμοι εγκατάστασης παρέχουν ένα απευθείας URL που μπορούν να χρησιμοποιήσουν οι έμποροι για να εγκαταστήσουν την εφαρμογή σας. Όταν ένας χρήστης κάνει κλικ σε έναν σύνδεσμο εγκατάστασης, το Stripe αναλαμβάνει τη ροή εγκατάστασης και έπειτα τον ανακατευθύνει πίσω στο URI που έχετε ορίσει.

Προϋποθέσεις

Πριν χρησιμοποιήσετε συνδέσμους εγκατάστασης, ρυθμίστε το allowed_redirect_uris στο manifest της εφαρμογής σας:

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

Μορφή του συνδέσμου εγκατάστασης

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

Παράμετρος	Υποχρεωτική	Περιγραφή
`client_id`	Ναι	Το ID της εφαρμογής σας (π.χ. `com.tajo.brevo-integration`)
`redirect_uri`	Ναι	Πρέπει να αντιστοιχεί σε ένα από τα `allowed_redirect_uris` σας
`state`	Συνιστάται	Τυχαία συμβολοσειρά για προστασία από CSRF

Παράμετροι ανακατεύθυνσης

Μετά από μια επιτυχή εγκατάσταση, το Stripe ανακατευθύνει τον χρήστη στο redirect_uri σας με τις παρακάτω παραμέτρους ερωτήματος:

Παράμετρος	Περιγραφή
`user_id`	Το ID χρήστη Stripe του λογαριασμού που κάνει την εγκατάσταση
`account_id`	Το ID λογαριασμού Stripe (π.χ. `acct_xxxxx`)
`state`	Η τιμή `state` που δώσατε (για την επαλήθευση CSRF)
`install_signature`	Υπογραφή HMAC που επιβεβαιώνει ότι η εγκατάσταση είναι έγκυρη

Παράδειγμα URL ανακατεύθυνσης:

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

Προστασία από CSRF

Χρησιμοποιείτε πάντα την παράμετρο state για να αποτρέψετε επιθέσεις πλαστογράφησης αιτημάτων από άλλους ιστότοπους (CSRF):

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

Επαλήθευση της υπογραφής

Επαληθεύστε το install_signature χρησιμοποιώντας το μυστικό υπογραφής της εφαρμογής σας:

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

Χρησιμοποιείτε πάντα το crypto.timingSafeEqual για τη σύγκριση υπογραφών, ώστε να αποτρέπετε επιθέσεις χρονισμού. Μη χρησιμοποιείτε ποτέ απλή σύγκριση συμβολοσειρών (===).

Μυστικό υπογραφής

Το μυστικό υπογραφής της εφαρμογής σας είναι διαθέσιμο στο Stripe Dashboard, στις ρυθμίσεις της εφαρμογής σας. Χρησιμοποιήστε το για να:

Επαληθεύετε τις υπογραφές εγκατάστασης από τις ανακατευθύνσεις callback
Ελέγχετε την εγκυρότητα των payloads webhook από το Stripe
Πιστοποιείτε τα αιτήματα ανάμεσα στο backend σας και το Stripe

Αποθηκεύστε το μυστικό υπογραφής με ασφάλεια:

# Set as environment variable
export STRIPE_APP_SIGNING_SECRET="whsec_xxxxx"

Μην ενσωματώνετε ποτέ μυστικά υπογραφής στον πηγαίο κώδικά σας και μην τα καταχωρίζετε σε σύστημα ελέγχου εκδόσεων.

Deep links

Τα deep links οδηγούν τους χρήστες απευθείας σε μια συγκεκριμένη προβολή μέσα στο εγκατεστημένο Stripe App σας. Χρησιμοποιήστε τα για να κατευθύνετε τους χρήστες από εξωτερικές επικοινωνίες (email, ειδοποιήσεις, σελίδες υποστήριξης) στο σχετικό σημείο της εφαρμογής.

Μορφή του URL ενός deep link

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

Στοιχείο	Περιγραφή	Παράδειγμα
`MODE`	`live` ή `test`	`live`
`acct_ID`	Το ID του λογαριασμού Stripe προορισμού	`acct_1234567890`
`PAGE`	Η διαδρομή της σελίδας στο Dashboard	`customers/cus_xxxxx`
`APP_ID`	Το ID της εφαρμογής σας	`com.tajo.brevo-integration`
`TARGET`	`drawer` ή `modal`	`drawer`
`VIEWPORT_ID`	Το viewport που θα ανοίξει	`stripe.dashboard.customer.detail`

Στόχος	Συμπεριφορά	Περίπτωση χρήσης
`drawer`	Ανοίγει την εφαρμογή στο πλευρικό πλαίσιο (drawer)	Προεπιλεγμένη αλληλεπίδραση με την εφαρμογή, με το περιεχόμενο δίπλα στη σελίδα
`modal`	Ανοίγει την εφαρμογή σε παράθυρο modal πλήρους οθόνης	Εστιασμένες ροές εργασίας, onboarding, σύνθετες φόρμες

Παραδείγματα deep links

Άνοιγμα της προβολής λεπτομερειών πελάτη στο 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

Άνοιγμα της ροής onboarding

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

Άνοιγμα της προβολής λεπτομερειών πληρωμής σε λειτουργία test

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

Δημιουργία deep links μέσω κώδικα

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

Χρήση των deep links στις επικοινωνίες

Τα deep links είναι ιδιαίτερα χρήσιμα σε:

Ειδοποιήσεις email: «Δείτε την κατάσταση συγχρονισμού Brevo για αυτόν τον πελάτη»
Απαντήσεις υποστήριξης: «Κάντε κλικ εδώ για να ελέγξετε τις ρυθμίσεις ενσωμάτωσης»
Email onboarding: «Ολοκληρώστε τη ρύθμιση του Brevo»
Ειδοποιήσεις σφάλματος: «Ελέγξτε το πρόβλημα συγχρονισμού για τον πελάτη 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>

Συνδυασμός συνδέσμων εγκατάστασης και deep links

Για την καλύτερη δυνατή εμπειρία onboarding, συνδυάστε τους συνδέσμους εγκατάστασης με deep links μετά την εγκατάσταση:

Ο χρήστης κάνει κλικ σε έναν σύνδεσμο εγκατάστασης από τον ιστότοπο ή το email σας
Ο χρήστης εγκαθιστά την εφαρμογή και ανακατευθύνεται στο URL callback σας
Το callback σας επεξεργάζεται την εγκατάσταση και ανακατευθύνει τον χρήστη σε ένα deep link που ανοίγει το viewport onboarding

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

Δοκιμάζετε πάντα τους συνδέσμους εγκατάστασης και τα deep links τόσο σε λειτουργία live όσο και σε test, ώστε να βεβαιώνεστε ότι λειτουργούν σωστά σε όλα τα περιβάλλοντα.