Poproś o wcześniejszy dostęp

Podaj imię oraz adres e-mail lub numer telefonu. Wyślemy Ci informacje o dostępie do Tajo.

Na tej stronie

Akcje poinstalacyjne i onboarding

Akcje poinstalacyjne decydują o tym, co dzieje się zaraz po zainstalowaniu Twojej aplikacji Stripe przez użytkownika. Dobrze zaprojektowane doświadczenie po instalacji prowadzi użytkownika przez konfigurację i zwiększa wskaźnik aktywacji.

Typy akcji poinstalacyjnych

Stripe obsługuje cztery typy akcji poinstalacyjnych, konfigurowane w manifeście aplikacji:

1. Link do aplikacji (domyślnie)

Otwiera aplikację w domyślnym widoku szuflady. To zachowanie domyślne, jeśli nie podasz post_install_action:

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

Użytkownik widzi widok drawer.default aplikacji w panelu bocznym Stripe Dashboard.

2. Link do onboardingu

Otwiera dedykowany widok onboardingu aplikacji, dając skupione doświadczenie konfiguracji:

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

Wymaga to zadeklarowania widoku onboarding w manifeście:

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

3. Link do ustawień

Otwiera widok ustawień aplikacji, przydatny, gdy aplikacja wymaga kluczy API lub konfiguracji przed użyciem:

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

Wymaga to widoku settings:

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

4. Link do zewnętrznego adresu URL

Przekierowuje użytkownika na zewnętrzny adres URL w celu konfiguracji. Użyj tej opcji, gdy Twój proces onboardingu działa poza Stripe Dashboard:

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

Caution

Zewnętrzne adresy URL muszą używać HTTPS i powinny znaleźć się na liście allowed_redirect_uris. Zespół weryfikacyjny Stripe sprawdzi, czy zewnętrzny adres URL zapewnia działającą konfigurację.

Najlepsze praktyki onboardingu

Zrób to bezwysiłkowo

Ogranicz liczbę kroków potrzebnych do startu:

Wypełniaj dane z góry, korzystając z kontekstu konta Stripe
Stosuj rozsądne wartości domyślne dla opcji konfiguracyjnych
Pozwól pomijać kroki opcjonalne, dając jasną ścieżkę do ich uzupełnienia później
Pokazuj postęp za pomocą wskaźników kroków w procesach wieloetapowych

Zrób to konfigurowalnym

Pozwól użytkownikom dostosować integrację do swoich potrzeb:

Opcje mapowania danych, pozwól wybrać, które pola Stripe synchronizują się z Brevo
Częstotliwość synchronizacji, zaoferuj tryb w czasie rzeczywistym, co godzinę lub raz dziennie
Synchronizacja wybiórcza, pozwól wybrać, których klientów lub produkty synchronizować
Preferencje powiadomień, skonfiguruj alerty o błędach synchronizacji i ważnych zdarzeniach

Zrób to trafnym

Pokaż wartość od razu:

Podgląd synchronizowanych danych przed włączeniem integracji
Pokaż, co się wydarzy, gdy użytkownik ukończy konfigurację
Udostępnij synchronizację testową, aby zweryfikować połączenie
Wyświetl wskaźniki sukcesu po zakończeniu pierwszej synchronizacji

Komponent OnboardingView

Komponent OnboardingView renderuje się w skupionym oknie modalnym, gdy użytkownik zainstaluje aplikację:

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;

Proces logowania z SignInView

Jeśli Twoja aplikacja wymaga zalogowania się do konta zewnętrznego (na przykład Tajo), użyj dedykowanego widoku logowania:

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

Uruchamianie z deep linku z parametrami zapytania

Za pomocą parametrów zapytania w deep linkach możesz uruchamiać konkretne kroki onboardingu lub wypełniać dane z góry:

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

Generuj deep linki, które wypełniają dane onboardingu z góry:

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

Obsługa powracających użytkowników

Gdy użytkownik otworzy Twoją aplikację po ukończeniu onboardingu, wykryj jego stan i pokaż odpowiedni widok:

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

Zapisuj status ukończenia onboardingu w Stripe Secret Store, aby rozpoznawać powracających użytkowników bez zewnętrznego wywołania API.