On this page

Post-installationshandlinger og onboarding

Post-installationshandlinger bestemmer hvad der sker umiddelbart efter en bruger installerer din Stripe App. En veldesignet post-installationsoplevelse guider brugere gennem opsætning og øger aktiveringsraterne.

Post-installationshandlingstyper

Stripe understøtter fire post-installationshandlingstyper, hver konfigureret i dit app-manifest:

1. Link til app (standard)

Åbner appen i standard skuffe-viewport. Dette er standardadfærden hvis ingen post_install_action er angivet:

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

2. Link til onboarding

Åbner appens dedikerede onboarding-visning og tilbyder en fokuseret opsætningsoplevelse:

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

Dette kræver et onboarding-viewport deklareret i dit manifest:

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

3. Link til indstillinger

Åbner appens indstillingsvisning, nyttig når appen kræver API-nøgler eller konfiguration før brug:

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

4. Link til ekstern URL

Omdirigerer brugeren til en ekstern URL til opsætning. Brug dette når dit onboardingflow lever uden for Stripe Dashboard:

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

Caution

Eksterne URL’er skal bruge HTTPS og bør være listet i dine allowed_redirect_uris. Stripe-gennemgangsteamet verificerer at den eksterne URL tilbyder en funktionel opsætningsoplevelse.

Bedste praksis for onboarding

Gør det ubesværet

Minimer antallet af trin der kræves for at komme i gang:

Udfyld oplysninger på forhånd tilgængeligt fra Stripe-kontokonteksten
Brug fornuftige standarder til konfigurationsindstillinger
Tillad spring over valgfrie trin med en klar vej til at fuldføre dem senere
Vis fremskridt med trinindikatorer til flertrinsflows

Gør det relevant

Vis værdi med det samme:

Forhåndsvis synkroniserede data inden du aktiverer integrationen
Vis hvad der vil ske når brugeren fuldfører opsætningen
Tilbyd en testsynk for at verificere at forbindelsen fungerer
Vis succesmetrics efter den indledende synk er fuldført

OnboardingView-komponenten

OnboardingView-komponenten gengives i en fokuseret modal når brugeren installerer appen:

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 {
      await storeBrevoApiKey(brevoApiKey);
      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' }}>
      <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>
          <TextField
            label="Brevo API Key"
            placeholder="xkeysib-..."
            value={brevoApiKey}
            onChange={(e) => setBrevoApiKey(e.target.value)}
            css={{ marginTop: 'medium' }}
          />
          <Button
            type="primary"
            onPress={handleConnect}
            disabled={!brevoApiKey || isConnecting}
            css={{ marginTop: 'medium' }}
          >
            {isConnecting ? 'Connecting...' : 'Connect Brevo'}
          </Button>
        </Box>
      )}

      {step === 2 && (
        <Box>
          <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>
          <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>
          <Button type="primary" onPress={() => {}}>Go to Dashboard</Button>
        </Box>
      )}
    </Box>
  );
};

export default OnboardingView;

Håndtering af tilbagevendende brugere

Når en bruger åbner din app efter at have fuldført onboarding, registrer deres tilstand og vis den relevante visning:

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

Gem onboarding-fuldførelsesstatus i Stripe Secret Store så du kan registrere tilbagevendende brugere uden et eksternt API-kald.