Demandez un accès anticipé

Indiquez votre prénom ainsi qu’une adresse e-mail ou un numéro de téléphone. Nous vous recontacterons pour vous communiquer les modalités d’accès à Tajo.

Sur cette page

Actions post-installation et onboarding

Les actions post-installation déterminent ce qui se passe immédiatement après qu’un utilisateur a installé votre Stripe App. Une expérience post-installation bien conçue accompagne les utilisateurs dans la configuration et augmente les taux d’activation.

Types d’action post-installation

Stripe prend en charge quatre types d’action post-installation, chacun se configurant dans le manifest de votre application :

1. Lien vers l’application (par défaut)

Ouvre l’application dans le viewport drawer par défaut. C’est le comportement appliqué lorsque aucune valeur post_install_action n’est indiquée :

{
  "post_install_action": {
    "type": "default"
  }
}

L’utilisateur voit le viewport drawer.default de l’application dans la barre latérale du Dashboard Stripe.

2. Lien vers l’onboarding

Ouvre la vue d’onboarding dédiée de l’application, pour une expérience de configuration concentrée :

{
  "post_install_action": {
    "type": "onboarding"
  }
}

Cela suppose qu’un viewport onboarding soit déclaré dans votre manifest :

{
  "ui_extension": {
    "views": [
      {
        "viewport": "stripe.dashboard.onboarding",
        "component": "OnboardingView"
      }
    ]
  },
  "post_install_action": {
    "type": "onboarding"
  }
}

3. Lien vers les paramètres

Ouvre la vue des paramètres de l’application, utile lorsque celle-ci exige des clés API ou une configuration avant utilisation :

{
  "post_install_action": {
    "type": "settings"
  }
}

Cela suppose un viewport settings :

{
  "ui_extension": {
    "views": [
      {
        "viewport": "stripe.dashboard.settings",
        "component": "SettingsView"
      }
    ]
  },
  "post_install_action": {
    "type": "settings"
  }
}

4. Lien vers une URL externe

Redirige l’utilisateur vers une URL externe pour la configuration. Utilisez ce type lorsque votre parcours d’onboarding se déroule en dehors du Dashboard Stripe :

{
  "post_install_action": {
    "type": "external",
    "url": "https://app.tajo.io/stripe/setup"
  }
}

Caution

Les URL externes doivent utiliser HTTPS et figurer dans vos allowed_redirect_uris. L’équipe de revue de Stripe vérifiera que l’URL externe propose une expérience de configuration fonctionnelle.

Bonnes pratiques d’onboarding

Rendez-le sans effort

Réduisez au minimum le nombre d’étapes nécessaires pour démarrer :

Pré-remplissez les informations disponibles depuis le contexte du compte Stripe
Utilisez des valeurs par défaut judicieuses pour les options de configuration
Autorisez à passer les étapes facultatives, avec un chemin clair pour les terminer plus tard
Affichez la progression avec des indicateurs d’étape pour les parcours en plusieurs étapes

Rendez-le personnalisable

Laissez les utilisateurs adapter l’intégration à leurs besoins :

Options de correspondance des données, laissez les utilisateurs choisir les champs Stripe synchronisés vers Brevo
Fréquence de synchronisation, proposez une synchronisation en temps réel, horaire ou quotidienne
Synchronisation sélective, laissez les utilisateurs choisir quels clients ou produits synchroniser
Préférences de notification, configurez les alertes en cas d’erreur de synchronisation ou d’événement important

Rendez-le pertinent

Montrez la valeur immédiatement :

Prévisualisez les données synchronisées avant d’activer l’intégration
Montrez ce qui va se passer une fois la configuration terminée
Proposez une synchronisation de test pour vérifier que la connexion fonctionne
Affichez des indicateurs de réussite une fois la synchronisation initiale terminée

Composant OnboardingView

Le composant OnboardingView s’affiche dans une modale dédiée au moment où l’utilisateur installe l’application :

import {
  Box,
  Button,
  Inline,
  Icon,
  Banner,
  TextField,
  Select,
  Divider,
} from '@stripe/ui-extension-sdk/ui';
import type { ExtensionContextValue } from '@stripe/ui-extension-sdk/context';
import { useState } from 'react';

const OnboardingView = ({ environment, userContext }: ExtensionContextValue) => {
  const [step, setStep] = useState(1);
  const [brevoApiKey, setBrevoApiKey] = useState('');
  const [syncMode, setSyncMode] = useState('realtime');
  const [isConnecting, setIsConnecting] = useState(false);
  const [error, setError] = useState<string | null>(null);

  const totalSteps = 3;

  const handleConnect = async () => {
    setIsConnecting(true);
    setError(null);

    try {
      // Store the API key securely
      await storeBrevoApiKey(brevoApiKey);

      // Verify the connection
      const result = await verifyBrevoConnection(brevoApiKey);

      if (result.success) {
        setStep(2);
      } else {
        setError('Unable to connect to Brevo. Please check your API key.');
      }
    } catch (err) {
      setError('Connection failed. Please try again.');
    } finally {
      setIsConnecting(false);
    }
  };

  return (
    <Box css={{ padding: 'large' }}>
      {/* Progress indicator */}
      <Inline css={{ marginBottom: 'large' }}>
        Step {step} of {totalSteps}
      </Inline>

      {error && (
        <Banner type="critical" title="Connection Error">
          {error}
        </Banner>
      )}

      {step === 1 && (
        <Box>
          <Inline css={{ fontWeight: 'bold', fontSize: 'large' }}>
            Connect Your Brevo Account
          </Inline>
          <Inline css={{ marginTop: 'small', color: 'secondary' }}>
            Enter your Brevo API key to start syncing customer data.
          </Inline>

          <TextField
            label="Brevo API Key"
            placeholder="xkeysib-..."
            value={brevoApiKey}
            onChange={(e) => setBrevoApiKey(e.target.value)}
            css={{ marginTop: 'medium' }}
          />

          <Inline css={{ marginTop: 'xsmall', color: 'secondary', fontSize: 'small' }}>
            Find your API key in Brevo under Settings &gt; SMTP &amp; API &gt; API Keys
          </Inline>

          <Button
            type="primary"
            onPress={handleConnect}
            disabled={!brevoApiKey || isConnecting}
            css={{ marginTop: 'medium' }}
          >
            {isConnecting ? 'Connecting...' : 'Connect Brevo'}
          </Button>
        </Box>
      )}

      {step === 2 && (
        <Box>
          <Inline css={{ fontWeight: 'bold', fontSize: 'large' }}>
            Configure Sync Settings
          </Inline>

          <Select
            label="Sync Mode"
            value={syncMode}
            onChange={(value) => setSyncMode(value)}
            css={{ marginTop: 'medium' }}
          >
            <option value="realtime">Real-time (recommended)</option>
            <option value="hourly">Every hour</option>
            <option value="daily">Once per day</option>
          </Select>

          <Divider css={{ marginY: 'medium' }} />

          <Button type="primary" onPress={() => setStep(3)}>
            Continue
          </Button>
          <Button type="secondary" onPress={() => setStep(1)}>
            Back
          </Button>
        </Box>
      )}

      {step === 3 && (
        <Box>
          <Banner type="default" title="Ready to Sync">
            Your Brevo account is connected. Tajo will begin syncing
            customer data automatically.
          </Banner>

          <Box css={{ marginTop: 'medium' }}>
            <Inline css={{ fontWeight: 'bold' }}>What happens next:</Inline>
            <ul>
              <li>Existing Stripe customers will sync to Brevo contacts</li>
              <li>New customers and events will sync in real-time</li>
              <li>View sync status on any customer's detail page</li>
            </ul>
          </Box>

          <Button type="primary" onPress={() => {/* Navigate to dashboard */}}>
            Go to Dashboard
          </Button>
        </Box>
      )}
    </Box>
  );
};

export default OnboardingView;

Parcours de connexion avec SignInView

Si votre application demande aux utilisateurs de se connecter à un compte externe (comme Tajo), utilisez une vue de connexion dédiée :

import {
  Box,
  Button,
  Inline,
  TextField,
  Banner,
  Link,
} from '@stripe/ui-extension-sdk/ui';
import { useState } from 'react';

const SignInView = ({ onSignInComplete }) => {
  const [email, setEmail] = useState('');
  const [password, setPassword] = useState('');
  const [isLoading, setIsLoading] = useState(false);
  const [error, setError] = useState<string | null>(null);

  const handleSignIn = async () => {
    setIsLoading(true);
    setError(null);

    try {
      const response = await fetch('https://api.tajo.io/v1/auth/stripe-app', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ email, password }),
      });

      if (!response.ok) {
        throw new Error('Invalid credentials');
      }

      const { token } = await response.json();

      // Store the auth token securely in Stripe's Secret Store
      await storeAuthToken(token);

      onSignInComplete();
    } catch (err) {
      setError('Sign-in failed. Please check your credentials and try again.');
    } finally {
      setIsLoading(false);
    }
  };

  return (
    <Box css={{ padding: 'large' }}>
      <Inline css={{ fontWeight: 'bold', fontSize: 'large' }}>
        Sign in to Tajo
      </Inline>
      <Inline css={{ marginTop: 'small', color: 'secondary' }}>
        Connect your Tajo account to enable Brevo sync.
      </Inline>

      {error && (
        <Banner type="critical" title="Sign-in Failed">
          {error}
        </Banner>
      )}

      <TextField
        label="Email"
        type="email"
        value={email}
        onChange={(e) => setEmail(e.target.value)}
        css={{ marginTop: 'medium' }}
      />

      <TextField
        label="Password"
        type="password"
        value={password}
        onChange={(e) => setPassword(e.target.value)}
        css={{ marginTop: 'small' }}
      />

      <Button
        type="primary"
        onPress={handleSignIn}
        disabled={!email || !password || isLoading}
        css={{ marginTop: 'medium' }}
      >
        {isLoading ? 'Signing in...' : 'Sign In'}
      </Button>

      <Link href="https://app.tajo.io/signup" external css={{ marginTop: 'small' }}>
        Don't have a Tajo account? Sign up
      </Link>
    </Box>
  );
};

Lancement par lien profond avec paramètres de requête

Vous pouvez lancer une étape d’onboarding précise ou pré-remplir des données à l’aide de paramètres de requête dans vos liens profonds :

import type { ExtensionContextValue } from '@stripe/ui-extension-sdk/context';

const OnboardingView = ({ environment }: ExtensionContextValue) => {
  // Access query parameters from the deep link
  const { queryParams } = environment;

  // Pre-fill step from query parameter
  const initialStep = queryParams?.step ? parseInt(queryParams.step) : 1;

  // Pre-fill API key from query parameter (e.g., from Tajo dashboard)
  const prefilledApiKey = queryParams?.brevo_key || '';

  // Source tracking for analytics
  const installSource = queryParams?.source || 'marketplace';

  const [step, setStep] = useState(initialStep);
  const [brevoApiKey, setBrevoApiKey] = useState(prefilledApiKey);

  // ... rest of onboarding logic
};

Générez des liens profonds qui pré-remplissent les données d’onboarding :

// From your Tajo dashboard, generate a link that pre-fills the Brevo API key
const onboardingLink = [
  'https://dashboard.stripe.com/live/acct_xxxxx/dashboard',
  '?apps[com.tajo.brevo-integration][modal]=stripe.dashboard.onboarding',
  '&apps[com.tajo.brevo-integration][queryParams][step]=1',
  '&apps[com.tajo.brevo-integration][queryParams][source]=tajo_dashboard',
].join('');

Gérer les utilisateurs qui reviennent

Lorsqu’un utilisateur ouvre votre application après avoir terminé l’onboarding, détectez son état et affichez la vue appropriée :

const MainView = ({ environment, userContext }: ExtensionContextValue) => {
  const [authState, setAuthState] = useState<'loading' | 'signed-out' | 'onboarding' | 'ready'>('loading');

  useEffect(() => {
    checkUserState().then((state) => {
      setAuthState(state);
    });
  }, []);

  switch (authState) {
    case 'loading':
      return <Spinner label="Loading..." />;
    case 'signed-out':
      return <SignInView onSignInComplete={() => setAuthState('onboarding')} />;
    case 'onboarding':
      return <OnboardingView onComplete={() => setAuthState('ready')} />;
    case 'ready':
      return <DashboardView />;
  }
};

Tip

Stockez l’état d’achèvement de l’onboarding dans le Stripe Secret Store, afin de détecter les utilisateurs qui reviennent sans passer par un appel API externe.