Požiadajte o skorý prístup

Uveďte svoje krstné meno a e-mailovú adresu alebo telefónne číslo. Pošleme Vám podrobnosti o prístupe k platforme Tajo.

Na tejto stránke

Akcie po inštalácii a onboarding

Akcie po inštalácii určujú, čo sa stane hneď po tom, ako si používateľ nainštaluje Vašu Stripe App. Dobre navrhnutý zážitok po inštalácii prevedie používateľov nastavením a zvyšuje mieru aktivácie.

Typy akcií po inštalácii

Stripe podporuje štyri typy akcií po inštalácii, pričom každý sa nastavuje v manifeste aplikácie:

1. Odkaz na aplikáciu (predvolené)

Otvorí aplikáciu v predvolenom viewporte typu drawer. Toto je predvolené správanie, ak nie je zadaná hodnota post_install_action:

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

Používateľ uvidí viewport drawer.default danej aplikácie v bočnom paneli Stripe Dashboard.

2. Odkaz na onboarding

Otvorí špecializované onboardingové zobrazenie aplikácie a poskytne sústredený zážitok z nastavenia:

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

Vyžaduje si to viewport onboarding deklarovaný vo Vašom manifeste:

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

3. Odkaz na nastavenia

Otvorí zobrazenie s nastaveniami aplikácie. Hodí sa vtedy, keď aplikácia pred použitím potrebuje API kľúče alebo konfiguráciu:

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

Vyžaduje si to viewport settings:

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

4. Odkaz na externú URL

Presmeruje používateľa na nastavenie na externú URL. Použite to vtedy, keď Váš onboardingový tok žije mimo Stripe Dashboard:

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

Caution

Externé URL musia používať HTTPS a mali by byť uvedené vo Vašom zozname allowed_redirect_uris. Kontrolný tím Stripe overí, či externá URL poskytuje funkčný priebeh nastavenia.

Osvedčené postupy pre onboarding

Urobte ho bezúsilným

Znížte počet krokov potrebných na začiatok:

Predvyplňte informácie dostupné z kontextu účtu Stripe
Použite rozumné predvolené hodnoty pre možnosti konfigurácie
Umožnite preskočiť voliteľné kroky a jasne ukážte, ako ich dokončiť neskôr
Zobrazujte priebeh pomocou indikátorov krokov pri viackrokových tokoch

Urobte ho prispôsobiteľným

Nechajte používateľov nastaviť si integráciu podľa vlastných potrieb:

Možnosti mapovania dát, nechajte používateľov vybrať, ktoré polia Stripe sa synchronizujú do Brevo
Frekvencia synchronizácie, ponúknite synchronizáciu v reálnom čase, každú hodinu alebo raz denne
Selektívna synchronizácia, nechajte používateľov vybrať, ktorých zákazníkov alebo ktoré produkty synchronizovať
Predvoľby notifikácií, nastavte upozornenia na chyby synchronizácie alebo dôležité udalosti

Urobte ho relevantným

Ukážte hodnotu okamžite:

Zobrazte náhľad synchronizovaných dát ešte pred zapnutím integrácie
Ukážte, čo sa stane, keď používateľ dokončí nastavenie
Ponúknite testovaciu synchronizáciu, ktorou si používateľ overí funkčné pripojenie
Zobrazte metriky úspechu po dokončení prvej synchronizácie

Komponent OnboardingView

Komponent OnboardingView sa vykreslí v sústredenom modálnom okne, keď si používateľ nainštaluje aplikáciu:

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;

Prihlasovací tok s komponentom SignInView

Ak Vaša aplikácia vyžaduje, aby sa používatelia prihlásili do externého účtu (napríklad Tajo), použite samostatné prihlasovacie zobrazenie:

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

Spustenie cez deep link s parametrami dotazu

Pomocou parametrov dotazu v deep linkoch môžete spustiť konkrétne kroky onboardingu alebo predvyplniť dáta:

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

Vygenerujte deep linky, ktoré predvyplnia onboardingové dáta:

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

Práca s vracajúcimi sa používateľmi

Keď používateľ otvorí Vašu aplikáciu po dokončení onboardingu, zistite jeho stav a zobrazte mu príslušné zobrazenie:

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

Stav dokončenia onboardingu ukladajte do Stripe Secret Store, aby ste vracajúcich sa používateľov rozpoznali bez volania externého API.