expo-seaart-tiktok-share

Expo native module for sharing local images and videos to TikTok on Android and iOS.

This package is for development builds or bare/native Expo projects. It cannot work inside Expo Go because TikTok Share Kit requires native Android and iOS code.

Official References

• TikTok Share Kit for Android: https://developers.tiktok.com/doc/share-kit-android-quickstart-v2/
• TikTok Share Kit for iOS: https://developers.tiktok.com/doc/share-kit-ios-quickstart-v2/

Features

• isAvailable() checks whether TikTok is installed.
• shareImage(localFileUri, photoLibraryLocalIdentifier?) shares a local image.
• shareVideo(localFileUri, photoLibraryLocalIdentifier?) shares a local video.
• Android uses TikTok Share Kit v2, FileProvider, package visibility queries, and a result activity.
• iOS uses TikTok Share Kit v2, AppDelegate URL handling, and TikTokRedirectURI.
• iOS can share an existing Photos asset when you pass expo-image-picker's assetId, avoiding a duplicate Photos item when the asset is accessible.

Quick Start

1. Configure your TikTok Developer app.
2. Install this package.
3. Add the config plugin to app.json or app.config.js.
4. Rebuild the native app.
5. Call isAvailable, then shareImage or shareVideo.

TikTok Setup

Create or update a TikTok Developer app for TikTok Share Kit.

Android requirements:

• Register the Android package name used by your app.
• Register the signing certificate fingerprint required by TikTok for that package.

iOS requirements:

• Register the iOS bundle identifier used by your app.
• Register the same clientKey you pass to this plugin.
• Register the iOS share redirectURI.

Two iOS redirect URI styles are supported:

• Custom scheme, simple for local/example apps: yourtiktokclientkey://tiktok/share-callback.
• HTTPS Universal Link, recommended for production: https://your-domain.example/tiktok/share-callback.

For HTTPS redirects, the plugin adds applinks:<host> to Associated Domains, but your app domain must still serve a valid apple-app-site-association file.

Install

pnpm add expo-seaart-tiktok-share
# or
npm install expo-seaart-tiktok-share

If your app lets users pick media from the photo library, install expo-image-picker too:

npx expo install expo-image-picker

This repository uses pnpm as the canonical package manager. npm install commands are provided for npm-based host apps. Keep using npx expo ... for Expo CLI steps in both pnpm and npm projects.

Configure

Add the config plugin:

{
  "expo": {
    "plugins": [
      [
        "expo-seaart-tiktok-share",
        {
          "clientKey": "yourtiktokclientkey",
          "redirectURI": "yourtiktokclientkey://tiktok/share-callback"
        }
      ]
    ],
    "ios": {
      "infoPlist": {
        "NSPhotoLibraryUsageDescription": "This app needs photo library access to share selected media to TikTok.",
        "NSPhotoLibraryAddUsageDescription": "This app saves media to the photo library before sharing it to TikTok when needed."
      }
    }
  }
}

You can also provide values through environment variables:

• EXPO_PUBLIC_TIKTOK_CLIENT_KEY or TIKTOK_CLIENT_KEY
• EXPO_PUBLIC_TIKTOK_REDIRECT_URI or TIKTOK_REDIRECT_URI

The plugin writes:

• Android Manifest meta-data for the TikTok client key
• Android package visibility queries for TikTok variants
• Android FileProvider configuration for local image/video files
• expo.seaart.tiktok.share.ExpoSeaartTiktokShareResultActivity
• iOS LSApplicationQueriesSchemes, TikTokClientKey, URL schemes, and redirect URI
• iOS Associated Domains entitlement only when the redirect URI is HTTPS
• iOS TikTok pods and AppDelegate URL handling

Rebuild

After adding or changing plugin config, regenerate and rebuild the native app:

npx expo prebuild --clean

Run Android:

npx expo run:android

Run iOS:

npx expo run:ios --device

If your iOS workflow does not install pods automatically, run this before npx expo run:ios --device:

cd ios
pod install
cd ..

Native config changes do not apply through Metro hot reload. Reinstall the app after changing clientKey, redirectURI, bundle identifier, package name, or signing certificate.

Usage

import { isAvailable, shareImage, shareVideo } from 'expo-seaart-tiktok-share';

const available = await isAvailable();
if (!available) {
  throw new Error('TikTok is not installed');
}

await shareVideo('file:///data/user/0/com.example/cache/demo.mp4');
await shareImage('/data/user/0/com.example/cache/demo.jpg');

// iOS: when sharing media picked from the photo library, pass ImagePicker's assetId
// to avoid saving a duplicate copy into the user's library.
await shareImage(asset.uri, asset.assetId);

With expo-image-picker:

import * as ImagePicker from 'expo-image-picker';
import { shareImage, shareVideo } from 'expo-seaart-tiktok-share';

const result = await ImagePicker.launchImageLibraryAsync({
  mediaTypes: ImagePicker.MediaTypeOptions.All,
  quality: 1,
});

if (!result.canceled && result.assets[0]) {
  const asset = result.assets[0];
  if (asset.type === 'video') {
    await shareVideo(asset.uri, asset.assetId);
  } else {
    await shareImage(asset.uri, asset.assetId);
  }
}

shareImage and shareVideo accept local file paths. A file:// URI is normalized before it is passed to TikTok Share Kit.

On iOS, TikTok Share Kit requires a PHAsset local identifier. If photoLibraryLocalIdentifier is provided, the module shares the existing Photos asset. If it is omitted or cannot be resolved, the module saves the local file to Photos first and shares the newly-created asset.

API

function isAvailable(): Promise<boolean>;

function shareImage(
  localFileUri: string,
  photoLibraryLocalIdentifier?: string | null
): Promise<TiktokShareResult>;

function shareVideo(
  localFileUri: string,
  photoLibraryLocalIdentifier?: string | null
): Promise<TiktokShareResult>;

type TiktokShareResult = {
  success: boolean;
  state?: string;
  errorCode?: number;
  subErrorCode?: number;
  errorMsg?: string;
};

Platform Notes

Android:

• Uses com.tiktok.open.sdk:tiktok-open-sdk-core:2.2.0.
• Uses com.tiktok.open.sdk:tiktok-open-sdk-share:2.2.0.
• The clientKey must match the app package and signing certificate registered in TikTok Developer Portal.

iOS:

• Depends on TikTokOpenSDKCore and TikTokOpenShareSDK.
• Requires redirectURI; missing config rejects with TIKTOK_REDIRECT_URI_MISSING.
• Needs photo library usage descriptions. The example includes NSPhotoLibraryUsageDescription and NSPhotoLibraryAddUsageDescription.
• For custom scheme redirects, the plugin adds the redirect scheme to CFBundleURLSchemes.
• For HTTPS redirects, the plugin adds Associated Domains, but you must maintain the domain and AASA file.

Troubleshooting

TikTok installed: false

Install TikTok on a real device. Simulators may not have TikTok installed and may not support the full native share flow.

TIKTOK_CLIENT_KEY_MISSING

Set clientKey in the config plugin, then run npx expo prebuild --clean and reinstall the app.

TIKTOK_REDIRECT_URI_MISSING

Set redirectURI in the config plugin, then run npx expo prebuild --clean and reinstall the iOS app. The value must also be registered in TikTok Developer Portal.

iOS opens TikTok but does not return to the app

Check that:

• redirectURI exactly matches the value registered in TikTok Developer Portal.
• The custom scheme exists in Info.plist for custom scheme redirects.
• Associated Domains and apple-app-site-association are correct for HTTPS redirects.
• AppDelegate.swift contains TikTokURLHandler.handleOpenURL.

Android share cannot read the selected file

Regenerate native files and check that AndroidManifest.xml contains the FileProvider authority ${applicationId}.tiktokshare.fileprovider and the resource @xml/tiktok_share_file_paths.

Example

The example app is under example/. See example/README.md for the full setup and troubleshooting guide. Run Expo prebuild only from that directory.

cd example
pnpm install
npx expo prebuild --clean
npx expo run:android
npx expo run:ios

Using npm:

cd example
npm install
npx expo prebuild --clean
npx expo run:android
npx expo run:ios

Fill clientKey and redirectURI in example/app.json before running a real share flow. Do not run npx expo prebuild --clean from the package root. The package root contains the Expo module source, while example/ is the Expo app that should generate native Android and iOS projects.

The example targets Expo SDK 55 with [email protected] and [email protected], matching the versions bundled by Expo 55.