Заявете ранен достъп

Посочете името си и имейл адрес или телефонен номер. Ще Ви изпратим информация за достъп до Tajo.

На тази страница

Действия след инсталиране и въвеждане в работа

Действията след инсталиране определят какво се случва непосредствено след като потребителят инсталира Вашия Stripe App. Добре проектираното преживяване след инсталиране превежда потребителите през настройката и повишава процента на активиране.

Типове действия след инсталиране

Stripe поддържа четири типа действия след инсталиране, всеки от които се конфигурира в манифеста на Вашия app:

1. Връзка към app (по подразбиране)

Отваря app в drawer viewport по подразбиране. Това е поведението по подразбиране, ако не е зададено post_install_action:

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

Потребителят вижда viewport drawer.default на app в страничната лента на таблото на Stripe.

2. Връзка към въвеждане в работа

Отваря специалния изглед за въвеждане в работа на app и осигурява съсредоточено преживяване при настройката:

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

Това изисква в манифеста Ви да е деклариран viewport onboarding:

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

3. Връзка към настройките

Отваря изгледа с настройките на app, което е полезно, когато app изисква API ключове или конфигурация преди употреба:

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

Това изисква viewport settings:

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

4. Връзка към външен URL

Пренасочва потребителя към външен URL за настройка. Използвайте това, когато Вашият поток за въвеждане в работа е извън таблото на Stripe:

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

Caution

Външните URL адреси трябва да използват HTTPS и да бъдат изброени във Вашия allowed_redirect_uris. Екипът за преглед на Stripe ще провери дали външният URL предоставя работещо преживяване при настройката.

Добри практики за въвеждане в работа

Направете го безпроблемно

Сведете до минимум броя на стъпките, необходими за начало на работата:

Попълвайте предварително информацията, налична от контекста на акаунта в Stripe
Използвайте разумни стойности по подразбиране за опциите за конфигурация
Позволявайте пропускане на незадължителните стъпки с ясен път те да бъдат изпълнени по-късно
Показвайте напредъка с индикатори за стъпките при многостъпковите потоци

Направете го адаптируемо

Позволете на потребителите да конфигурират интеграцията според нуждите си:

Опции за съпоставяне на данни, оставете потребителите да избират кои полета от Stripe да се синхронизират към Brevo
Честота на синхронизация, предложете синхронизация в реално време, на час или веднъж дневно
Избирателна синхронизация, оставете потребителите да избират кои клиенти или продукти да се синхронизират
Предпочитания за известия, конфигурирайте известия за грешки при синхронизация или за важни събития

Направете го уместно

Покажете стойност веднага:

Показвайте предварителен преглед на синхронизираните данни, преди интеграцията да бъде включена
Показвайте какво ще се случи, когато потребителят завърши настройката
Предоставяйте опция за тестова синхронизация, за да се потвърди, че връзката работи
Показвайте метрики за успех, след като първоначалната синхронизация приключи

Компонент OnboardingView

Компонентът OnboardingView се рендерира в съсредоточен модален прозорец, когато потребителят инсталира app:

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;

Поток за вход със SignInView

Ако Вашият app изисква потребителите да влизат във външен акаунт (например в Tajo), използвайте специален изглед за вход:

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

Стартиране чрез дълбока връзка с параметри на заявката

Можете да стартирате конкретни стъпки от въвеждането в работа или да попълните данни предварително чрез параметри на заявката в дълбоките връзки:

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

Генерирайте дълбоки връзки, които попълват предварително данните за въвеждането в работа:

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

Работа със завръщащи се потребители

Когато потребител отвори Вашия app, след като е завършил въвеждането в работа, разпознайте състоянието му и покажете подходящия изглед:

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

Съхранявайте статуса за завършено въвеждане в работа в Secret Store на Stripe, за да разпознавате завръщащите се потребители без външно API извикване.