--- title: "Link di installazione e deep link | Tajo" description: "Genera URL di installazione per distribuire l’app e deep link per portare gli utenti a view specifiche dell’app" url: https://tajo.io/it/docs/stripe-apps/install-links/ markdown: https://tajo.io/it/docs/stripe-apps/install-links.md lang: it-IT author: "Set Noa" author_url: https://tajo.io/it/set-noa/ robots: noindex --- Richiedi l’accesso anticipato Inserisci il tuo nome e indirizzo email aziendale. Ti invieremo un link per confermare la richiesta di accesso a Tajo. # Link di installazione e deep link [Set Noa](https://tajo.io/it/set-noa/) I link di installazione ti permettono di distribuire la tua Stripe App fuori dal marketplace, mentre i deep link portano gli utenti direttamente a view specifiche all’interno dell’app installata. Entrambi sono essenziali per rendere fluidi i flussi di onboarding e integrazione. Caution **Stato: pianificata, non realizzata.** Tajo non ha un’app Stripe, quindi oggi nulla di questa sezione può essere installato. Gli identificatori dell’app, gli URL e le credenziali presenti in questa pagina sono segnaposto illustrativi, non endpoint reali. ## Link di installazione I link di installazione forniscono un URL diretto che i merchant possono usare per installare la tua app. Quando un utente clicca su un link di installazione, Stripe gestisce il flusso di installazione e poi reindirizza all’URI che hai indicato. ### Prerequisiti Prima di usare i link di installazione, configura `allowed_redirect_uris` nel manifest della tua app: ```json { "id": "com.tajo.brevo-integration", "allowed_redirect_uris": [ "https://tajo.io/stripe/callback", "https://tajo.io/stripe/oauth/complete" ] } ``` ### Formato del link di installazione ``` https://marketplace.stripe.com/oauth/v2/authorize?client_id=APP_ID&redirect_uri=REDIRECT_URI&state=STATE_VALUE ``` | Parametro | Obbligatorio | Descrizione | | --- | --- | --- | | `client_id` | Sì | L’ID della tua app (per esempio `com.tajo.brevo-integration`) | | `redirect_uri` | Sì | Deve corrispondere a uno dei tuoi `allowed_redirect_uris` | | `state` | Consigliato | Stringa casuale per la protezione CSRF | ### Parametri di reindirizzamento Dopo un’installazione riuscita, Stripe reindirizza l’utente al tuo `redirect_uri` con questi parametri di query: | Parametro | Descrizione | | --- | --- | | `user_id` | L’ID utente Stripe dell’account che installa l’app | | `account_id` | L’ID account Stripe (per esempio `acct_xxxxx`) | | `state` | Il valore `state` che hai fornito (per la verifica CSRF) | | `install_signature` | Firma HMAC per verificare che l’installazione sia legittima | Esempio di URL di reindirizzamento: ``` https://tajo.io/stripe/callback ?user_id=usr_xxxxx &account_id=acct_xxxxx &state=abc123random &install_signature=sig_xxxxx ``` ### Protezione CSRF Usa sempre il parametro `state` per prevenire gli attacchi di cross-site request forgery: ```javascript 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'); }; ``` ### Verifica della firma Verifica `install_signature` usando il signing secret della tua app: ```javascript 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 Usa sempre `crypto.timingSafeEqual` per confrontare le firme, così eviti i timing attack. Non usare mai la semplice uguaglianza tra stringhe (`===`). ### Signing secret Il signing secret della tua app è disponibile nella Stripe Dashboard, nelle impostazioni dell’app. Usalo per: - Verificare le firme di installazione ricevute nelle callback di reindirizzamento - Validare i payload dei webhook inviati da Stripe - Autenticare le richieste tra il tuo backend e Stripe Conserva il signing secret in modo sicuro: ```bash # Set as environment variable export STRIPE_APP_SIGNING_SECRET="whsec_xxxxx" ``` Non inserire mai i signing secret direttamente nel codice sorgente e non committarli nel controllo di versione. ## Deep link I deep link portano gli utenti direttamente a una view specifica della tua Stripe App installata. Usali per indirizzare gli utenti dalle comunicazioni esterne (email, notifiche, pagine di assistenza) al contesto pertinente dell’app. ### Formato dell’URL di un deep link ``` https://dashboard.stripe.com/MODE/acct_ID/PAGE?apps[APP_ID][TARGET]=VIEWPORT_ID ``` | Componente | Descrizione | Esempio | | --- | --- | --- | | `MODE` | `live` oppure `test` | `live` | | `acct_ID` | ID dell’account Stripe di destinazione | `acct_1234567890` | | `PAGE` | Percorso della pagina della Dashboard | `customers/cus_xxxxx` | | `APP_ID` | L’ID della tua app | `com.tajo.brevo-integration` | | `TARGET` | `drawer` oppure `modal` | `drawer` | | `VIEWPORT_ID` | Il viewport da aprire | `stripe.dashboard.customer.detail` | ### Target drawer e modal a confronto | Target | Comportamento | Caso d’uso | | --- | --- | --- | | `drawer` | Apre l’app nel pannello laterale (drawer) | Interazione predefinita con l’app, contesto affiancato alla pagina | | `modal` | Apre l’app in un overlay modale a schermo intero | Flussi che richiedono concentrazione, onboarding, moduli complessi | ### Esempi di deep link #### Aprire la view di dettaglio del cliente nel drawer ``` https://dashboard.stripe.com/live/acct_xxxxx/customers/cus_xxxxx ?apps[com.tajo.brevo-integration][drawer]=stripe.dashboard.customer.detail ``` #### Aprire le impostazioni in una modale ``` https://dashboard.stripe.com/live/acct_xxxxx/settings ?apps[com.tajo.brevo-integration][modal]=stripe.dashboard.settings ``` #### Aprire il flusso di onboarding ``` https://dashboard.stripe.com/live/acct_xxxxx/dashboard ?apps[com.tajo.brevo-integration][modal]=stripe.dashboard.onboarding ``` #### Aprire la view di dettaglio del pagamento in modalità test ``` https://dashboard.stripe.com/test/acct_xxxxx/payments/pi_xxxxx ?apps[com.tajo.brevo-integration][drawer]=stripe.dashboard.payment.detail ``` ### Generare deep link in modo programmatico ```javascript 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', }); ``` ### Usare i deep link nelle comunicazioni I deep link sono particolarmente utili in: - **Notifiche email**: “Vedi lo stato della sincronizzazione Brevo per questo cliente” - **Risposte dell’assistenza**: “Clicca qui per controllare le impostazioni della tua integrazione” - **Email di onboarding**: “Completa la configurazione di Brevo” - **Avvisi di errore**: “Controlla il problema di sincronizzazione del cliente X” ```html View Brevo Profile in Stripe ``` ## Combinare link di installazione e deep link Per la migliore esperienza di onboarding, combina i link di installazione con i deep link post-installazione: 1. L’utente clicca su un **link di installazione** dal tuo sito o da un’email 2. L’utente installa l’app e viene reindirizzato al tuo URL di callback 3. La tua callback elabora l’installazione e reindirizza l’utente a un **deep link** che apre il viewport di onboarding ```javascript 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 sempre i link di installazione e i deep link sia in modalità live sia in modalità test, per essere sicuro che funzionino correttamente in tutti gli ambienti.