Be om tidlig tilgang

Skriv inn fornavn og e-postadresse på jobb. Vi sender deg en lenke for å bekrefte forespørselen om tilgang til Tajo.

På denne siden

Handlinger etter installasjon og onboarding

Handlinger etter installasjon bestemmer hva som skjer umiddelbart etter at en bruker installerer Stripe-appen din. En godt utformet opplevelse rett etter installasjonen leder brukeren gjennom oppsettet og øker aktiveringsgraden.

Caution

Status: planlagt. Det finnes ennå ingen Tajo-app i Stripe App Marketplace. App-identifikatorene, URL-ene og legitimasjonen på denne siden er illustrerende plassholdere, ikke ekte endepunkter.

Typer handlinger etter installasjon

Stripe støtter fire typer handlinger etter installasjon, og hver av dem konfigureres i appmanifestet ditt:

1. Lenke til appen (standard)

Åpner appen i standard drawer-viewport. Dette skjer som standard hvis ingen post_install_action er angitt:

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

Brukeren ser appens drawer.default-viewport i sidemenyen i Stripe Dashboard.

2. Lenke til onboarding

Åpner appens egen onboarding-visning og gir et fokusert oppsettsforløp:

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

Dette krever et onboarding-viewport deklarert i manifestet ditt:

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

3. Lenke til innstillinger

Åpner appens innstillingsvisning, nyttig når appen trenger API-nøkler eller konfigurasjon før den kan brukes:

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

Dette krever et settings-viewport:

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

4. Lenke til en ekstern URL

Sender brukeren videre til en ekstern URL for oppsett. Bruk dette når onboarding-flyten din ligger utenfor Stripe Dashboard:

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

Caution

Eksterne URL-er må bruke HTTPS og bør stå oppført i allowed_redirect_uris. Stripes gjennomgangsteam kontrollerer at den eksterne URL-en gir et oppsettsforløp som faktisk fungerer.

Beste praksis for onboarding

Gjør det enkelt

Hold antallet trinn som trengs for å komme i gang nede:

Fyll ut på forhånd med informasjon som er tilgjengelig fra Stripe-kontokonteksten
Bruk fornuftige standardvalg for konfigurasjonsalternativene
La brukeren hoppe over valgfrie trinn, med en tydelig vei til å fullføre dem senere
Vis fremdriften med trinnindikatorer i flertrinnsflyter

Gjør det tilpassbart

La brukerne sette opp integrasjonen slik de trenger den:

Valg for datamapping, la brukerne velge hvilke Stripe-felter som synkroniseres til Brevo
Synkroniseringsfrekvens, tilby synkronisering i sanntid, hver time eller daglig
Selektiv synkronisering, la brukerne velge hvilke kunder eller produkter som skal synkroniseres
Varslingsvalg, konfigurer varsler for synkroniseringsfeil eller viktige hendelser

Gjør det relevant

Vis verdien med én gang:

Forhåndsvis dataene som synkroniseres før integrasjonen aktiveres
Vis hva som kommer til å skje når brukeren fullfører oppsettet
Tilby en testsynkronisering slik at brukeren kan bekrefte at tilkoblingen virker
Vis resultattall når den første synkroniseringen er ferdig

OnboardingView-komponenten

Komponenten OnboardingView vises i en fokusert modal når brukeren 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 {
      // 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;

Innloggingsflyt med SignInView

Hvis appen din krever at brukerne logger inn på en ekstern konto (som Tajo), bruker du en egen innloggingsvisning:

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.example.com/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>
  );
};

Dyplenker med spørringsparametere

Du kan starte bestemte onboarding-trinn eller forhåndsutfylle data ved hjelp av spørringsparametere i dyplenker:

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

Generer dyplenker som forhåndsutfyller onboarding-data:

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

Håndter brukere som kommer tilbake

Når en bruker åpner appen din etter fullført onboarding, oppdager du hvilken tilstand brukeren er i og viser riktig 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

Lagre statusen for fullført onboarding i Stripe Secret Store, slik at du kan oppdage brukere som kommer tilbake uten å måtte kalle et eksternt API.