Setting Up the SDK

Installing the SDK is a three-part process:

  1. Install the npm package into your React Native project.
  2. Configure the native Android project (Android Setup).
  3. Configure the native iOS project (iOS Setup).

Because this wrapper ships a native Android module and a native iOS module, you cannot skip the native configuration, even though it is driven by React Native's autolinking.


1. Install the Package

The SDK is installed directly from its GitHub repository. npm can consume any Git-hosted package by URL, so you point it at the Inkrypt GitHub repo and a tag (or branch, or commit).

From the root of your React Native project:

npm install github:inkrypt-mobile/mobile-sdk-react-native#v0.1.2
# or, equivalent full URL form
npm install git+https://github.com/inkrypt-mobile/mobile-sdk-react-native.git#v0.1.2
# or with yarn
yarn add github:inkrypt-mobile/mobile-sdk-react-native#v0.1.2

Pinning Strategies

RefExampleWhen to use
Tag (recommended)#v0.1.2Stable release, most common choice
Commit SHA#a1b2c3dMaximum reproducibility (locks to an exact commit)
Branch#mainTracking active development, avoid in production

Leaving the ref off entirely resolves to the repo's default branch at install time, which will drift and break reproducibility.

Verify the Entry in package.json

After installation, your package.json will contain an entry like this:

{
  "dependencies": {
    "@inkrypt/react-native-inkrypt-video-player": "github:inkrypt-mobile/mobile-sdk-react-native#v0.1.2"
  }
}

The key is still @inkrypt/react-native-inkrypt-video-player, that comes from the package's own package.json and is how you import it, but the value is the GitHub reference.


2. Autolinking

React Native 0.60+ autolinks the native modules for both platforms. You do not need to edit MainApplication.kt or AppDelegate.swift to register the package, autolinking handles it on the next build.

However, autolinking does not pull in the native binaries the SDKs depend on. Those must be added manually:

  • Android: register the local Maven repository and add the Media3 dependency. See Android Setup.
  • iOS: install pods so the InkryptVideos.xcframework is picked up. See iOS Setup.

3. Import the Module

Once both platforms are configured and you have run a clean build, you can import from anywhere in your app:

import {
  InkryptVideoPlayerView,
  type InkPlayerParams,
  type InkryptVideoPlayerMethods,
} from '@inkrypt/react-native-inkrypt-video-player';

Proceed to Basic Usage to render the player.


Installing from a Local Path

Alternatively, if you have the sdk locally, you can install it as a file dependency:

npm install /absolute/path/to/mobile-sdk-react-native

You must also configure Metro to avoid module duplication, since the SDK has its own node_modules that would otherwise conflict with the host app's copy of React.

Update metro.config.js:

const path = require('path');
const escape = require('escape-string-regexp');
const exclusionList = require('metro-config/src/defaults/exclusionList');
const { getDefaultConfig, mergeConfig } = require('@react-native/metro-config');
const sdkRoot = path.resolve(__dirname, '/absolute/path/to/mobile-sdk-react-native');
const pak = require(path.join(sdkRoot, 'package.json'));
const modules = Object.keys({ ...pak.peerDependencies });
const config = {
  watchFolders: [sdkRoot],
  resolver: {
    blacklistRE: exclusionList(
      modules.map(
        (m) => new RegExp(`^${escape(path.join(sdkRoot, 'node_modules', m))}\\/.*$`)
      )
    ),
    extraNodeModules: modules.reduce((acc, name) => {
      acc[name] = path.join(__dirname, 'node_modules', name);
      return acc;
    }, {}),
  },
};
module.exports = mergeConfig(getDefaultConfig(__dirname), config);

Restart Metro with --reset-cache after changing this file.


Android Setup

The React Native wrapper depends on the native Inkrypt Android SDK, which is distributed as an AAR through a GitHub-hosted Maven repository. After running npm install, you need to point Gradle at that repository and add one explicit dependency to bring in the Media3 (ExoPlayer) APIs the SDK relies on.

For a detailed walkthrough of the native Android SDK itself, see the Native Android Integration - Setting Up the SDK documentation.


How the GitHub-Hosted Repo Works

The Inkrypt Android SDK is published to a public GitHub repository that serves as a raw Maven repository. Each AAR and its metadata live under a standard Maven group/artifact/version path inside the repo, and Gradle fetches them over plain HTTPS via raw.githubusercontent.com.

The canonical URL shape is:

https://raw.githubusercontent.com/<org>/<repo>/<branch>/repo

For the Inkrypt Android SDK this resolves to:

https://raw.githubusercontent.com/inkryptvideos/android-maven-repo/main/repo

No authentication, no tokens, no credentials, Gradle treats it like any other remote Maven repo.


1. Register the Repository

Open android/settings.gradle (or settings.gradle.kts) and add the GitHub-hosted Maven URL inside dependencyResolutionManagement. If the block does not exist, create it.

Groovy - settings.gradle

dependencyResolutionManagement {
  repositoriesMode.set(RepositoriesMode.PREFER_SETTINGS)
  repositories {
    google()
    mavenCentral()
    maven {
      url = uri("https://raw.githubusercontent.com/inkryptvideos/android-maven-repo/main/repo")
    }
  }
}

Kotlin DSL - settings.gradle.kts

dependencyResolutionManagement {
  repositoriesMode.set(RepositoriesMode.PREFER_SETTINGS)
  repositories {
    google()
    mavenCentral()
    maven {
      url = uri("https://raw.githubusercontent.com/inkryptvideos/android-maven-repo/main/repo")
    }
  }
}

Pinning to a Specific Commit (Optional)

Pointing at main means you get whatever the tip of the branch contains at resolve time. For reproducible builds, pin to a specific commit SHA instead:

maven {
  url = uri("https://raw.githubusercontent.com/inkrypt-mobile/android-maven-repo/<COMMIT_SHA>/repo")
}

2. Add the Media3 Dependency

The native SDK exposes public APIs that reference androidx.media3 types. Your app must depend on media3-common explicitly so those types resolve at compile time.

Open android/app/build.gradle (or build.gradle.kts) and add:

dependencies {
  implementation 'androidx.media3:media3-common:1.4.0'
}

3. Confirm minSdkVersion and Architecture Flags

Verify the following in android/build.gradle:

buildscript {
  ext {
    minSdkVersion = 24        // Must be >= 24
  }
}

And in android/gradle.properties:

newArchEnabled=false // Must be false

4. Rebuild

From the project root:

cd android && ./gradlew clean && cd ..
npx react-native run-android

If Gradle resolves successfully and the app installs, the native SDK is wired up correctly.


Troubleshooting

Could not find com.inkryptvideos.android:inkryptvideos-android:<version>

Gradle reached the repository but could not find the requested artifact. Possible causes:

  • The version in the dependency declaration does not exist under com/inkryptvideos/android/inkryptvideos-android/ in the GitHub repo. Browse the repo on GitHub to confirm which versions are available.

Received status code 404 from the Maven URL

The URL path is wrong. Check the branch name (main vs master), that /repo is present at the end, and that you are using raw.githubusercontent.com (not github.com).

Unresolved reference: androidx.media3.common.* during build

You are missing the media3-common dependency from Step 2.

App crashes on launch with NoSuchMethodError

A version mismatch between the native SDK and your app's Media3 dependency. Align your media3-common version with the one bundled in the native SDK (1.4.0 at time of writing).

Developer Mode blocks playback in debug builds

By design, the native SDK blocks playback when Developer Options or USB Debugging are enabled. During development, pass tolerateDeveloperMode: true in the player params - see Basic Usage.


Using a Local Maven Repo (Offline / Development)

If you have a locally published Maven repo on disk, for example when testing an unreleased native SDK build - swap the GitHub URL for a file path:

maven {
  url = uri("absolute/path/to/android-maven-repo/repo")
}

Every other step is identical.


iOS Setup

The React Native wrapper ships a CocoaPods .podspec that declares the native InkryptVideos.xcframework as a dependency. After running npm install, you need to run pod install so CocoaPods fetches the framework and wires it into the Xcode project.

For a detailed walkthrough of the native iOS SDK itself, see the Native iOS Integration - Setting Up the SDK documentation.


1. Install Pods

From the project root:

cd ios
pod install
cd ..

If pod install reports the Inkrypt framework as missing or stale, refresh the local pod index and re-run:

pod repo update
pod install

If you see cached-reference issues (usually after switching branches or upgrading the package), do a full reset:

npm uninstall @inkrypt/react-native-inkrypt-video-player
npm install github:inkrypt-mobile/mobile-sdk-react-native#v0.1.2
cd ios && pod install && cd ..

Reinstall using the same GitHub ref you originally installed with - see Setting Up the SDK → Install the Package for the pinning strategies.


2. Set the Deployment Target

The native SDK requires iOS 16.1 or later. Update your Podfile at the top:

platform :ios, '16.1'

Then also update the target in Xcode:

  1. Open ios/<YourApp>.xcworkspace
  2. Select your app target
  3. General → Minimum Deployments → set iOS to 16.1

3. Verify Code Signing

The XCFramework is signed. Make sure your app target has a valid Team selected under Signing & Capabilities, otherwise linking will fail at archive time.


4. Run on a Physical Device

FairPlay DRM, the content-protection layer used by the native SDK, is not supported on the iOS Simulator. You must build and run on a physical iPhone or iPad to exercise video playback.

npx react-native run-ios --device

Or launch from Xcode directly with a device selected in the toolbar.


Troubleshooting

pod install fails with "Unable to find a specification for InkryptVideos"

Run pod repo update to refresh the pod index, then pod install again.

Build error: No such module 'InkryptVideos'

Open the .xcworkspace file (not the .xcodeproj) - pods are only linked into the workspace.

App launches but video does not play on Simulator

FairPlay is not available in the Simulator. This is expected. Test on a real device.

Linker warning: Could not find or use auto-linked framework 'InkryptVideos'

Re-run pod install from the ios/ directory. If the warning persists, delete ios/Pods, ios/Podfile.lock, and ios/build, then run pod install again.

Archive fails with a code signing error related to the framework

Ensure you are using the official InkryptVideos.xcframework provided by CocoaPods. Do not rename or modify its contents.