Kérj korai hozzáférést

Add meg a keresztnevedet, valamint egy e-mail-címet vagy telefonszámot. Hamarosan elküldjük a Tajo eléréséhez szükséges információkat.

Ezen az oldalon

Telepítés utáni műveletek és bevezetés

A telepítés utáni műveletek határozzák meg, hogy mi történik közvetlenül azután, hogy egy felhasználó telepíti a Stripe appodat. A jól megtervezett telepítés utáni élmény végigvezeti a felhasználót a beállításon, és növeli az aktiválási arányt.

Telepítés utáni művelettípusok

A Stripe négy telepítés utáni művelettípust támogat, mindegyiket az app manifestjében állítod be:

1. Hivatkozás az appra (alapértelmezett)

Megnyitja az appot az alapértelmezett drawer viewportban. Ez az alapértelmezett viselkedés, ha nem adsz meg post_install_action értéket:

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

A felhasználó az app drawer.default viewportját látja a Stripe irányítópult oldalsávjában.

2. Hivatkozás a bevezetésre

Megnyitja az app dedikált bevezetési nézetét, így fókuszált beállítási élményt ad:

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

Ehhez egy onboarding viewport deklarálása szükséges a manifestben:

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

3. Hivatkozás a beállításokra

Megnyitja az app beállítási nézetét. Hasznos, ha az app használat előtt API kulcsot vagy konfigurációt igényel:

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

Ehhez egy settings viewport szükséges:

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

4. Hivatkozás külső URL-re

Átirányítja a felhasználót egy külső URL-re a beállításhoz. Ezt akkor használd, ha a bevezetési folyamatod a Stripe irányítópulton kívül él:

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

Caution

A külső URL-eknek HTTPS-t kell használniuk, és szerepelniük kell az allowed_redirect_uris listádban. A Stripe ellenőrző csapata megvizsgálja, hogy a külső URL valóban működő beállítási élményt ad-e.

Bevezetési jó gyakorlatok

Legyen könnyű

Csökkentsd minimálisra az induláshoz szükséges lépések számát:

Töltsd ki előre az információt, amit a Stripe fiók kontextusából megkapsz
Használj észszerű alapértékeket a konfigurációs beállításokhoz
Engedd kihagyni az opcionális lépéseket, világos úttal a későbbi befejezéshez
Mutasd a haladást lépésjelzőkkel a többlépéses folyamatokban

Legyen testreszabható

Hagyd, hogy a felhasználók az igényeikhez igazítsák az integrációt:

Adatmegfeleltetési lehetőségek, hadd válasszák ki, mely Stripe mezők szinkronizálódjanak a Brevóba
Szinkronizálási gyakoriság, kínálj valós idejű, óránkénti vagy napi szinkronizálást
Szelektív szinkronizálás, hadd válasszák ki, mely vásárlók vagy termékek szinkronizálódjanak
Értesítési beállítások, riasztások beállítása szinkronizálási hibákra vagy fontos eseményekre

Legyen releváns

Mutasd meg azonnal az értéket:

Nézd meg előre a szinkronizált adatokat, mielőtt bekapcsolod az integrációt
Mutasd meg, mi fog történni, amikor a felhasználó befejezi a beállítást
Adj tesztszinkronizálási lehetőséget, hogy ellenőrizhető legyen a kapcsolat
Jelenítsd meg a sikermutatókat az első szinkronizálás után

Az OnboardingView komponens

Az OnboardingView komponens fókuszált modálban jelenik meg, amikor a felhasználó telepíti az appot:

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;

Bejelentkezési folyamat a SignInView komponenssel

Ha az appod külső fiókba (például Tajo fiókba) való bejelentkezést igényel, használj dedikált bejelentkezési nézetet:

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

Mélyhivatkozásos indítás lekérdezési paraméterekkel

A mélyhivatkozások lekérdezési paramétereivel adott bevezetési lépéseket indíthatsz el, vagy adatokat tölthetsz ki előre:

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

Készíts olyan mélyhivatkozásokat, amelyek előre kitöltik a bevezetési adatokat:

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

Visszatérő felhasználók kezelése

Amikor a felhasználó a bevezetés befejezése után nyitja meg az appot, ismerd fel az állapotát, és a megfelelő nézetet mutasd:

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

Tárold a bevezetés befejezettségét a Stripe Secret Store-ban, így külső API hívás nélkül felismered a visszatérő felhasználókat.