Erken erişim talep edin

Adınızı ve e-posta adresinizi veya telefon numaranızı paylaşın. Tajo erişim ayrıntıları için sizinle iletişime geçeceğiz.

Bu sayfada

Kurulum sonrası işlemler ve başlangıç akışı

Kurulum sonrası işlemler, bir kullanıcı Stripe App’inizi kurduktan hemen sonra ne olacağını belirler. İyi tasarlanmış bir kurulum sonrası deneyim, kullanıcılara kurulum boyunca rehberlik eder ve aktivasyon oranlarını artırır.

Kurulum sonrası işlem türleri

Stripe, her biri uygulama manifestonuzda yapılandırılan dört kurulum sonrası işlem türünü destekler:

1. Uygulamaya bağlantı (varsayılan)

Uygulamayı varsayılan çekmece viewport’unda açar. post_install_action belirtilmezse varsayılan davranış budur:

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

Kullanıcı, Stripe Dashboard kenar çubuğunda uygulamanın drawer.default viewport’unu görür.

2. Başlangıç akışına bağlantı

Uygulamanın kendine ait başlangıç görünümünü açar ve odaklanmış bir kurulum deneyimi sunar:

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

Bunun için manifestonuzda tanımlanmış bir onboarding viewport’u gerekir:

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

3. Ayarlara bağlantı

Uygulamanın ayarlar görünümünü açar. Uygulama kullanılmadan önce API anahtarı veya yapılandırma gerektiriyorsa kullanışlıdır:

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

Bunun için bir settings viewport’u gerekir:

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

4. Harici URL’ye bağlantı

Kullanıcıyı kurulum için harici bir URL’ye yönlendirir. Başlangıç akışınız Stripe Dashboard dışında yaşıyorsa bunu kullanın:

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

Caution

Harici URL’ler HTTPS kullanmalı ve allowed_redirect_uris listenizde yer almalıdır. Stripe inceleme ekibi, harici URL’nin çalışan bir kurulum deneyimi sunduğunu doğrulayacaktır.

Başlangıç akışı için en iyi uygulamalar

Zahmetsiz hale getirin

Başlamak için gereken adım sayısını en aza indirin:

Stripe hesap bağlamından edinilebilen bilgileri önceden doldurun
Yapılandırma seçenekleri için makul varsayılanlar kullanın
İsteğe bağlı adımların atlanmasına izin verin ve bunları daha sonra tamamlamak için net bir yol sunun
Çok adımlı akışlarda adım göstergeleriyle ilerlemeyi gösterin

Özelleştirilebilir hale getirin

Kullanıcıların entegrasyonu kendi ihtiyaçlarına göre yapılandırmasına izin verin:

Veri eşleme seçenekleri, kullanıcıların hangi Stripe alanlarının Brevo’ya senkronize edileceğini seçmesine izin verin
Senkronizasyon sıklığı, gerçek zamanlı, saatlik veya günlük senkronizasyon seçenekleri sunun
Seçmeli senkronizasyon, kullanıcıların hangi müşterilerin veya ürünlerin senkronize edileceğini seçmesine izin verin
Bildirim tercihleri, senkronizasyon hataları veya önemli olaylar için uyarıları yapılandırın

İlgili hale getirin

Değeri hemen gösterin:

Entegrasyonu etkinleştirmeden önce senkronize edilecek verileri önizletin
Kullanıcı kurulumu tamamladığında ne olacağını gösterin
Bağlantının çalıştığını doğrulamak için bir test senkronizasyonu seçeneği sunun
İlk senkronizasyon tamamlandıktan sonra başarı metriklerini gösterin

OnboardingView bileşeni

Kullanıcı uygulamayı kurduğunda OnboardingView bileşeni odaklanmış bir kalıcı pencerede görüntülenir:

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 ile giriş akışı

Uygulamanız kullanıcıların harici bir hesaba (örneğin Tajo’ya) giriş yapmasını gerektiriyorsa, özel bir giriş görünümü kullanın:

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

Sorgu parametreleriyle derin bağlantı başlatma

Derin bağlantılarda sorgu parametreleri kullanarak belirli başlangıç adımlarını açabilir veya verileri önceden doldurabilirsiniz:

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

Başlangıç verilerini önceden dolduran derin bağlantılar oluşturun:

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

Geri dönen kullanıcıları ele alma

Bir kullanıcı başlangıç akışını tamamladıktan sonra uygulamanızı açtığında, durumunu tespit edin ve uygun görünümü gösterin:

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

Başlangıç akışının tamamlanma durumunu Stripe Secret Store’da saklayın; böylece geri dönen kullanıcıları harici bir API çağrısı olmadan tespit edebilirsiniz.