Richiedi l’accesso anticipato

Inserisci il tuo nome e un indirizzo email o un numero di telefono. Ti contatteremo con tutte le informazioni per accedere a Tajo.

In questa pagina

Stripe Apps incorporate

Le Stripe Apps incorporate permettono alle piattaforme costruite su Stripe Connect di offrire le funzionalità di app di terze parti direttamente all’interno delle proprie dashboard. Con i componenti incorporati di Connect puoi dare ai tuoi account collegati l’accesso ad app come QuickBooks, Xero e Mailchimp senza che debbano passare dalla Stripe Dashboard.

Panoramica

Le app incorporate usano due componenti incorporati di Connect fondamentali:

app-install: mostra un pulsante di installazione per una Stripe App all’interno della UI della tua piattaforma
app-viewport: mostra uno specifico viewport dell’app all’interno della UI della tua piattaforma

Questo consente agli operatori di piattaforma di incorporare strumenti di contabilità, marketing e operativi direttamente nel proprio prodotto.

App supportate

Le app seguenti supportano l’incorporamento tramite i componenti di Connect:

App	Categoria	Caso d’uso
QuickBooks	Contabilità	Sincronizza pagamenti e fatture con QuickBooks
Xero	Contabilità	Contabilità e riconciliazione automatizzate
Mailchimp	Marketing	Sincronizza i dati dei clienti per le campagne email
App personalizzate	Qualsiasi	Le tue Stripe Apps sviluppate per la tua piattaforma

Tip

L’integrazione Tajo Brevo può essere incorporata nelle piattaforme Connect, permettendo agli account collegati di sincronizzare i propri dati Stripe con Brevo tramite l’interfaccia della piattaforma stessa.

Configurazione con la Account Sessions API

Per incorporare le app devi creare delle Account Session con i componenti opportuni abilitati:

Lato server: creare una Account Session

const stripe = require('stripe')('sk_live_...');

// Create an Account Session for the connected account
const accountSession = await stripe.accountSessions.create({
  account: 'acct_connected_account_id',
  components: {
    // Enable app install component
    app_install: {
      enabled: true,
      features: {
        allowed_apps: [
          'com.tajo.brevo-integration',
          'com.quickbooks.stripe-app'
        ],
      },
    },
    // Enable app viewport component
    app_viewport: {
      enabled: true,
      features: {
        allowed_apps: [
          'com.tajo.brevo-integration'
        ],
      },
    },
  },
});

// Return the client secret to your frontend
res.json({ clientSecret: accountSession.client_secret });

Lato client: inizializzare Connect.js

import { loadConnectAndInitialize } from '@stripe/connect-js';

// Initialize Connect.js with the account session
const stripeConnect = loadConnectAndInitialize({
  publishableKey: 'pk_live_...',
  fetchClientSecret: async () => {
    const response = await fetch('/api/account-session', {
      method: 'POST',
    });
    const { clientSecret } = await response.json();
    return clientSecret;
  },
});

Componente App Install

Il componente app-install mostra un pulsante di installazione che gli account collegati possono usare per installare una Stripe App:

JavaScript

// Create the app install element
const appInstall = stripeConnect.create('app-install');

// Set the app to install
appInstall.setApp('com.tajo.brevo-integration');

// Mount to a DOM element
const container = document.getElementById('app-install-container');
appInstall.mount(container);

// Listen for install events
appInstall.on('app_installed', (event) => {
  console.log('App installed:', event.app_id);
  // Show the app viewport after installation
  showAppViewport();
});

appInstall.on('app_uninstalled', (event) => {
  console.log('App uninstalled:', event.app_id);
});

React

import {
  ConnectAppInstall,
  ConnectComponentsProvider,
} from '@stripe/react-connect-js';

const AppInstallButton = () => {
  return (
    <ConnectComponentsProvider connectInstance={stripeConnect}>
      <ConnectAppInstall
        app="com.tajo.brevo-integration"
        onAppInstalled={(event) => {
          console.log('App installed:', event.app_id);
        }}
        onAppUninstalled={(event) => {
          console.log('App uninstalled:', event.app_id);
        }}
      />
    </ConnectComponentsProvider>
  );
};

Componente App Viewport

Il componente app-viewport mostra uno specifico viewport dell’app all’interno della tua piattaforma:

JavaScript

// Create the app viewport element
const appViewport = stripeConnect.create('app-viewport');

// Configure the viewport
appViewport.setApp('com.tajo.brevo-integration');
appViewport.setViewport('stripe.dashboard.customer.detail');

// Pass object context (e.g., customer ID)
appViewport.setObjectContext({
  id: 'cus_xxxxx',
  object: 'customer',
});

// Mount to a DOM element
const container = document.getElementById('app-viewport-container');
appViewport.mount(container);

React

import {
  ConnectAppViewport,
  ConnectComponentsProvider,
} from '@stripe/react-connect-js';

const BrevoCustomerView = ({ customerId }: { customerId: string }) => {
  return (
    <ConnectComponentsProvider connectInstance={stripeConnect}>
      <ConnectAppViewport
        app="com.tajo.brevo-integration"
        viewport="stripe.dashboard.customer.detail"
        objectContext={{
          id: customerId,
          object: 'customer',
        }}
      />
    </ConnectComponentsProvider>
  );
};

Schema dei metadata delle destination charge

Quando usi le app incorporate con le destination charge (frequenti nelle piattaforme Connect), i metadata dell’addebito trasportano dati strutturati che le integrazioni di contabilità e marketing possono consumare.

Integrazioni di contabilità

Per app come QuickBooks e Xero, i metadata delle destination charge seguono questo schema:

{
  "metadata": {
    "customer_id": "cus_platform_customer_id",
    "customer_email": "[email protected]",
    "product_name": "Premium Subscription",
    "product_id": "prod_xxxxx",
    "quantity": "1",
    "unit_amount": "4999",
    "currency": "usd",
    "platform_fee": "500",
    "platform_fee_currency": "usd",
    "tax_amount": "450",
    "tax_rate_id": "txr_xxxxx",
    "invoice_id": "inv_xxxxx",
    "order_id": "order_12345"
  }
}

Campo	Tipo	Descrizione
`customer_id`	string	Identificatore del cliente sulla piattaforma
`customer_email`	string	Email del cliente per l’abbinamento di fatture e ricevute
`product_name`	string	Nome visualizzato del prodotto per le voci di riga
`product_id`	string	ID prodotto Stripe
`quantity`	string	Quantità dell’articolo
`unit_amount`	string	Prezzo unitario nell’unità di valuta più piccola (centesimi)
`currency`	string	Codice valuta ISO di tre lettere
`platform_fee`	string	Importo della commissione applicativa nell’unità di valuta più piccola
`platform_fee_currency`	string	Valuta della commissione di piattaforma
`tax_amount`	string	Importo dell’imposta nell’unità di valuta più piccola
`tax_rate_id`	string	ID dell’aliquota fiscale Stripe applicata
`invoice_id`	string	ID della fattura associata
`order_id`	string	Identificatore interno dell’ordine sulla piattaforma

Integrazioni di marketing

Per app come Mailchimp e l’integrazione Tajo Brevo, i metadata abilitano la segmentazione dei clienti e il targeting delle campagne:

{
  "metadata": {
    "customer_id": "cus_xxxxx",
    "customer_email": "[email protected]",
    "customer_name": "Jane Smith",
    "product_category": "subscription",
    "product_name": "Pro Plan",
    "purchase_value": "4999",
    "currency": "usd",
    "is_first_purchase": "true",
    "referral_source": "partner_campaign",
    "subscription_interval": "monthly",
    "lifetime_value": "29994"
  }
}

Questi metadata abilitano automazioni Brevo come:

Serie di benvenuto per chi acquista per la prima volta (is_first_purchase: "true")
Campagne di upsell basate su product_category e purchase_value
Flussi di retention per i clienti in abbonamento basati su subscription_interval
Campagne di win-back rivolte ai clienti con lifetime_value elevato che abbandonano

Esempio di integrazione di piattaforma

Un’integrazione di piattaforma completa che incorpora l’app Tajo Brevo:

import { useState, useEffect } from 'react';
import {
  ConnectAppInstall,
  ConnectAppViewport,
  ConnectComponentsProvider,
} from '@stripe/react-connect-js';
import { loadConnectAndInitialize } from '@stripe/connect-js';

const TajoBrevoPlatformIntegration = ({ connectedAccountId, customerId }) => {
  const [stripeConnect, setStripeConnect] = useState(null);
  const [isInstalled, setIsInstalled] = useState(false);

  useEffect(() => {
    const instance = loadConnectAndInitialize({
      publishableKey: 'pk_live_...',
      fetchClientSecret: async () => {
        const res = await fetch('/api/account-session', {
          method: 'POST',
          headers: { 'Content-Type': 'application/json' },
          body: JSON.stringify({ accountId: connectedAccountId }),
        });
        const { clientSecret } = await res.json();
        return clientSecret;
      },
    });
    setStripeConnect(instance);
  }, [connectedAccountId]);

  if (!stripeConnect) return <div>Loading...</div>;

  return (
    <ConnectComponentsProvider connectInstance={stripeConnect}>
      {!isInstalled ? (
        <div>
          <h3>Connect Brevo via Tajo</h3>
          <p>Install the Tajo integration to sync customer data with Brevo.</p>
          <ConnectAppInstall
            app="com.tajo.brevo-integration"
            onAppInstalled={() => setIsInstalled(true)}
          />
        </div>
      ) : (
        <div>
          <h3>Brevo Customer Profile</h3>
          <ConnectAppViewport
            app="com.tajo.brevo-integration"
            viewport="stripe.dashboard.customer.detail"
            objectContext={{
              id: customerId,
              object: 'customer',
            }}
          />
        </div>
      )}
    </ConnectComponentsProvider>
  );
};

Considerazioni sulla sicurezza

Quando incorpori le app nella tua piattaforma:

Le Account Session scadono: creane di nuove quando serve, non memorizzare in cache i client secret
Controllo dello scope: usa allowed_apps per limitare quali app possono essere installate
Isolamento dei dati: i dati di ogni account collegato sono isolati, la piattaforma non può accedere ai dati dell’app
Header CSP: assicurati che la Content Security Policy della tua piattaforma consenta le connessioni a https://connect-js.stripe.com

Caution

I componenti delle app incorporate richiedono un’integrazione Connect con accesso alla Account Sessions API. Gli account Stripe standard non possono usare i componenti incorporati.

Stripe Apps incorporate

Panoramica

App supportate

Configurazione con la Account Sessions API

Lato server: creare una Account Session

Lato client: inizializzare Connect.js

Componente App Install

JavaScript

React

Componente App Viewport

JavaScript

React

Schema dei metadata delle destination charge

Integrazioni di contabilità

Integrazioni di marketing

Esempio di integrazione di piattaforma

Considerazioni sulla sicurezza

Richiedi l’accesso anticipato

Grazie, l’iscrizione è confermata.