> ## Documentation Index
> Fetch the complete documentation index at: https://learn.social.plus/llms.txt
> Use this file to discover all available pages before exploring further.

# Quick Start

> Your complete guide to building social apps with social.plus UIKit - from installation to your first component

Welcome to social.plus UIKit! This guide will get you from zero to a working social app in **under 15 minutes**. Follow these steps to add complete social features to your app.

## Quick Start Guide

<Steps>
  <Step title="Choose Your Platform">
    Select the UIKit that matches your development environment and install:

    <CardGroup cols={1}>
      <Card title="Install UIKit" icon="wrench">
        * [Native Mobile UIKit: iOS, Android](/uikit/getting-started/installation)
        * [Web UIKit: React](/uikit/getting-started/installation)
        * [Cross-Platform UIKit: Flutter, React Native](/uikit/getting-started/installation)
      </Card>
    </CardGroup>

    <Info>
      **Installation Options**: Choose **package installation** for quick setup or **GitHub forking** for complete customization. React Native and Flutter are only available through GitHub forking.
    </Info>
  </Step>

  <Step title="Get Your API Key">
    1. Visit the Admin Console
    2. Navigate to **Applications** → **Your App** → **Settings**
    3. Copy your API key and note your region (US, EU, or SG)

    <Note>
      Keep your API key secure. For production apps, implement proper server-side authentication.
    </Note>
  </Step>

  <Step title="Initialize UIKit & Authenticate a user">
    Install UIKit and set up with your API credentials (for more details, see the [authentication guide](/uikit/getting-started/authentication)):

    <CodeGroup>
      ```swift iOS theme={null}
      // Add to your AppDelegate or SceneDelegate
      import AmityUIKit

      AmityUIKitManager.setup(
          apiKey: "your-api-key",
          region: .US  // .US, .EU, or .SG
      )

      // Register user when the user accesses the feature
      AmityUIKitManager.registerDevice(
        withUserId: "USER_ID", 
        displayName: "Ali Connors", 
        authToken: "AUTH_TOKEN"
      )
      ```

      ```kotlin Android theme={null}
      // In your Application class
      class MyApplication : Application() {
          override fun onCreate() {
              super.onCreate()
              
              AmityUIKit4Manager.setup(
                  apiKey = "your-api-key",
                  endpoint = AmityEndpoint.US
              )
          }
      }

      // Register user when the user accesses the feature
      fun login(userId: String, authToken: String) {
        AmityCoreClient.login(
          userId = userId,
          sessionHandler = object : SessionHandler {
              override fun sessionWillRenewAccessToken(renewal: AccessTokenRenewal) {
                  renewal.renew()
                  }
                }
            ).authToken(authToken)
          .build()
          .submit()
          .subscribeOn(Schedulers.io())
          .doOnError {
              // Exception
          }
          .subscribe()
        }
      ```

      ```typescript React theme={null}
      import { AmityUIKitProvider } from '@amityco/ui-kit';
      import '@amityco/ui-kit/dist/index.css';

      const isGoogleBotOrInspectionTool: boolean = false // can add condition to check if user agent is google bot will be true

      function App() {
        return (
          <AmityUiKitProvider
            key={userId}
            apiKey={apiKey}
            userId={userId}
            apiRegion={apiRegion} //eu, us, or sg
            getAuthToken={getAuthToken} //for secure mode authentication
            onRouteChange={(page) => {
                console.log("Route changed to:", page); // integrate with your analytics service
            }}
            seoOptimizationEnabled={isGoogleBotOrInspectionTool} // default value is false, if pass true MQTT will be disabled.
          >
            <div
              style={{
                position: "absolute",
                left: 0,
                top: 0,
                width: "100vw",
                height: "100dvh",
              }}
            >
              <AmityUiKitSocial />
            </div>
          </AmityUiKitProvider>
        );
      }
      ```

      ```jsx React Native theme={null}
      import {
        AmityUiKitProvider,
        AmityUiKitSocial,
      } from 'amity-react-native-social-ui-kit';

      export default function App() {
        return (
          <AmityUiKitProvider
            apiKey="your-api-key"
            apiRegion="us"
            userId="user123"
            displayName="John Doe"
          >
            <AmityUiKitSocial />
          </AmityUiKitProvider>
        );
      }
      ```

      ```dart Flutter theme={null}
      import 'package:flutter/material.dart';
      import 'package:amity_uikit_beta_service/amity_uikit.dart';

      Future<void> main() async {
        WidgetsFlutterBinding.ensureInitialized();

        // 1. Initialize the SDK before showing any UIKit screen.
        await AmityUIKit().setup(
          apikey: 'YOUR_API_KEY',
          region: AmityEndpointRegion.sg, // .us, .eu, or .sg
        );

        runApp(const MyApp());
      }

      // 2. Register (log in) the user. registerDevice needs a BuildContext that
      // sits BELOW AmityUIKitProvider — see the next step for how AuthGate calls it.
      void login(BuildContext context) {
        AmityUIKit().registerDevice(
          context: context,
          userId: 'USER_ID',
          displayName: 'DISPLAY_NAME', // optional
          // authToken: 'AUTH_TOKEN',  // only when secure mode is enabled
          callback: (isSuccess, error) {
            if (!isSuccess) {
              debugPrint('Login failed: $error');
            }
          },
        );
      }
      ```
    </CodeGroup>
  </Step>

  <Step title="Add Your First Component">
    Start with a social feed or any component that fits your app:

    <CodeGroup>
      ```swift iOS theme={null}
      let socialHomePage = AmitySocialHomePage()
      let navigationViewController = AmitySwiftUIHostingNavigationController(rootView: socialHomePage)
      ```

      ```kotlin Android theme={null}
      @Composable
      fun composeSocialHomePage() {
      AmitySocialHomePage()
      }

      fun startAnActivity(context: Context) {
        val intent = Intent(
          context,
          AmitySocialHomePageActivity::class.java 
          )
          context.startActivity(intent)
      }
      ```

      ```jsx React theme={null}
      import React from 'react';
      import { AmityUiKitProvider, AmitySocialHomePage } from '@amityco/ui-kit';
      const SampleAmitySocialHomePage = () => {
        return (
          <AmityUiKitProvider
            apiKey="API_KEY"
            apiRegion="API_REGION"
            userId="userId"
            displayName="displayName"
            configs={config} //put your customized config json object
          >
            <AmitySocialHomePage />
          </AmityUiKitProvider>
        );
      };

      export default SampleAmitySocialHomePage;
      ```

      ```jsx React Native theme={null}
      import {
        AmitySocialHomePage,
        AmityUiKitProvider,
        } from 'amity-react-native-social-ui-kit';
        import React from 'react';
        import config from '../../uikit.config.json';
        <AmityUiKitProvider
          configs={config} //put your customized config json object
          apiKey="API_KEY"
          apiRegion="API_REGION"
          userId="userId"
          displayName="displayName"
          apiEndpoint="https://api.{API_REGION}.amity.co"
        />
      behaviour={{
      AmitySocialHomePageBehaviour: { onChooseTab: (tab) => console.log(tab) },
      }}
      >
      <AmitySocialHomePage />
      </AmityUiKitProvider>;
      ```

      ```dart Flutter theme={null}
      import 'package:flutter/material.dart';
      import 'package:amity_uikit_beta_service/amity_uikit.dart';
      import 'package:amity_uikit_beta_service/v4/utils/config_provider_widget.dart';

      void main() async {
        WidgetsFlutterBinding.ensureInitialized();

        // Initialize UIKit
        await AmityUIKit().setup(
          apikey: 'YOUR_API_KEY',
          region: AmityEndpointRegion.eu, // .us, .eu, or .sg
        );

        runApp(MyApp());
      }

      class MyApp extends StatelessWidget {
        @override
        Widget build(BuildContext context) {
          return AmityUIKitProvider(
            child: LoginGate(),
          );
        }
      }

      class LoginGate extends StatefulWidget {
        @override
        State<LoginGate> createState() => _LoginGateState();
      }

      class _LoginGateState extends State<LoginGate> {
        bool _loggedIn = false;
        String? _error;

        @override
        void initState() {
          super.initState();
          AmityUIKit().registerDevice(
            context: context,
            userId: 'userId1',
            callback: (isSuccess, error) {
              if (!mounted) return;
              setState(() {
                _loggedIn = isSuccess;
                _error = error;
              });
            },
          );
        }

        @override
        Widget build(BuildContext context) {
          if (_loggedIn) {
            return SocialHomePageConfigProviderWidget();
          }
          if (_error != null) {
            return Scaffold(body: Center(child: Text('Login failed: $_error')));
          }
          return const Scaffold(body: Center(child: CircularProgressIndicator()));
        }
      }
      ```
    </CodeGroup>
  </Step>
</Steps>

## Development Paths

UIKit offers four progressive customization levels. Start at the lowest level that solves today’s need—move up only when you hit a limitation. Each level layers on the previous one; no throwaway work.

<CardGroup cols={3}>
  <Card title="1. Dynamic UI" icon="wand-magic-sparkles" href="/uikit/customization/dynamic-ui">
    Remote + conditional configuration & layout: role‑based visibility, experiments, feature flags, runtime theme adjustments.

    <br />

    <br />

    Use when you need server‑driven variations without redeploys.
  </Card>

  <Card title="2. Component Styling" icon="paintbrush" href="/uikit/customization/component-styling">
    Targeted page / component / element overrides: icons, button styles, layout spacing, per‑feature navigation behavior.

    <br />

    <br />

    Use when a few components need deeper tweaks beyond tokens.
  </Card>

  <Card title="3. Fork & Extend" icon="code-fork" href="/uikit/customization/advanced-customization">
    Full source fork for new UX paradigms, custom data flows, or deep platform integrations.

    <br />

    <br />

    Use only when earlier layers cannot achieve your required behavior.
  </Card>
</CardGroup>

<Tip>
  Decision shortcut:

  * Role/experiment/change colors on-the-fly → <a href="/uikit/customization/dynamic-ui">Level 1: Dynamic UI</a>
  * Specific component/layout tweaks → <a href="/uikit/customization/component-styling">Level 2: Component Styling</a>
  * Net‑new interaction model → <a href="/uikit/customization/advanced-customization">Level 3: Fork & Extend</a>
</Tip>

<Note>
  You can safely prototype at Level 1 and graduate upward without rewriting work—higher levels augment, not replace, earlier configuration.
</Note>

## Installation Methods

UIKit offers two installation approaches to match your development needs:

<CardGroup cols={2}>
  <Card title="Package Installation" icon="cube">
    **Quick Setup (Recommended)**

    ✅ **Platforms**: iOS, Android, Web\
    ❌ **Not available**: Flutter, React Native

    * Managed dependencies and updates
    * Minimal configuration required
    * Perfect for most use cases
    * Easy version management
  </Card>

  <Card title="GitHub Fork" icon="code-fork">
    **Complete Customization**

    ✅ **All Platforms**: iOS, Android,Web, Flutter, React Native

    * Full source code access
    * Custom modifications possible
    * Advanced integrations
    * Maximum flexibility
  </Card>
</CardGroup>

<Info>
  **React Native Special Case**: React Native UIKit is only available through GitHub forking, giving you complete control over the implementation.
</Info>

## Use Case Examples

Choose your starting point based on what you want to build:

<Tabs>
  <Tab title="Social Media App">
    **Perfect for**: Instagram-like apps, social networks, content sharing platforms

    **Start with these components:**

    1. Social Feed - Display user posts and content
    2. User Profiles - User information and social connections
    3. Post Creation - Rich content creation tools
    4. Comments & Reactions - User engagement features

    **Timeline**: 1-2 weeks for MVP
  </Tab>

  <Tab title="Community Platform">
    **Perfect for**: Forums, interest groups, professional networks

    **Start with these components:**

    1. Communities - Group creation and management
    2. Community Feed - Group-specific content
    3. Member Management - Roles and permissions
    4. Moderation Tools - Content safety features

    **Timeline**: 2-3 weeks for MVP
  </Tab>

  <Tab title="Content Creator Platform">
    **Perfect for**: Influencer apps, creator tools, content platforms

    **Start with these components:**

    1. Story Creation - Rich multimedia stories
    2. Story Viewing - Immersive story experience
    3. Social Feed - Creator content distribution
    4. User Profiles - Creator showcase pages

    **Timeline**: 2-3 weeks for MVP
  </Tab>
</Tabs>

## Ready to Start?

Choose your next step based on your current status:

<CardGroup cols={3}>
  <Card title="New to UIKit?" icon="play" href="/uikit/getting-started/installation">
    **Start with Installation**

    Set up UIKit for your platform and get your development environment ready.
  </Card>

  <Card title="Already Installed?" icon="key" href="/uikit/getting-started/authentication">
    **Configure Authentication**

    Set up your API credentials and user authentication system.
  </Card>

  <Card title="Ready to Customize?" icon="puzzle-piece" href="/uikit/customization/overview">
    **Customize UIKit**

    Customize UIkit to match your app's branding and user experience.
  </Card>
</CardGroup>

<Tip>
  **Quick Win**: If you just want to see UIKit in action, follow our [5-minute setup guide](/uikit/getting-started/installation) and add a social feed to your app!
</Tip>