Docs: Instaread Player

Docs

Built for your developers.

The mobile SDK puts the Instaread player in your iOS, Android, React Native and Flutter apps today. The REST API and MCP server are coming soon.

Just want the player on your site? That’s the integrations guide →

Mobile SDK

Embed the Instaread Audio Player on top of relevant articles in your app, with background playback, lock-screen controls and a floating mini player. Pick your platform.

Use the latest version: for the best integration, always use the latest version of the SDK. Check the package page for the newest release: npm.

Requirements: React Native 0.76 or newer, on either architecture. One package covers both platforms. The native iOS and Android SDKs are bundled within it.

1
Install the package

Install the SDK from npm, then install the iOS pods.
Terminal
```
npm install @instaread-co/react-native-instaread-sdk
cd ios && pod install
```
2
Platform-specific setup

These are the platform-specific edits in the entire integration.

iOS

To enable background audio playback (so that audio continues playing when the app is in the background or the screen is locked), add the following configuration to your Info.plist:
ios/YourApp/Info.plist
```
<key>UIBackgroundModes</key>
<array>
    <string>audio</string>
</array>
```
Android

A. Add the native SDK to your build by including the following line in the dependencies in android/app/build.gradle:
android/app/build.gradle
```
implementation files("$rootDir/../node_modules/@instaread-co/react-native-instaread-sdk/android/libs/instaread-sdk.aar")
```
Android does not automatically include a library’s local .aar file in the app. This line ensures that the player is included in your build.

B. Request notification permission on Android 13 and above. Without this permission, the lock-screen media controls will not appear.
App.tsx
```
import { PermissionsAndroid, Platform } from 'react-native';

if (Platform.OS === 'android' && Platform.Version >= 33) {
  PermissionsAndroid.request(PermissionsAndroid.PERMISSIONS.POST_NOTIFICATIONS);
}
```

Configure the SDK once at your app’s root

Same code on iOS and Android. Replace yourslug with your Instaread publication name.

App.tsx

import { InstareadPlayer } from '@instaread-co/react-native-instaread-sdk';

// Before anything renders — e.g. at the top of App.tsx
InstareadPlayer.configure('yourslug');

4
Add the player to your article screen

We recommend placing it at the top, so that the audio player appears immediately after the article heading and before the article text.
ArticleScreen.tsx
```
import { InstareadPlayerView } from '@instaread-co/react-native-instaread-sdk';

<InstareadPlayerView articleUrl={article.canonicalUrl} />
```
Important: please ensure that articleUrl points to the article’s own page URL on your site, which is the same URL used by the web player.

Requirements: iOS 13.0 or newer and Xcode 26 or newer. Works with UIKit and SwiftUI, with no third-party dependencies.

1
Add the Swift package

In Xcode, choose File → Add Package Dependencies… and enter the URL of our GitHub repository. Choose Up to Next Major Version from 1.6.1, then add the InstareadSDK library to your app target.
Package URL
```
https://github.com/instaread-co/instaread-ios-sdk-spm
```
2
Enable background audio playback

So that audio continues playing when the app is in the background or the screen is locked, add the following configuration to your Info.plist:
Info.plist
```
<key>UIBackgroundModes</key>
<array>
    <string>audio</string>
</array>
```
3
Configure the SDK once at app start

Before anything renders: in application(_:didFinishLaunchingWithOptions:), or in your SwiftUI App’s init(). Replace yourslug with your Instaread publication name.
AppDelegate.swift
```
import InstareadSDK

InstareadPlayer.configure(publication: "yourslug")
```
4
Add the player to your article screen

We recommend placing it at the top, so that the audio player appears immediately after the article heading and before the article text.
UIKit
```
let player = InstareadPlayerView(articleUrl: "https://yoursite.com/your-article")
stackView.addArrangedSubview(player)
```
SwiftUI
```
WebInlinePlayerView(publication: "yourslug", articleUrl: "https://yoursite.com/your-article")
```
In UIKit, create the view in code. It cannot be added from a storyboard or xib.

Important: please ensure that articleUrl points to the article’s own page URL on your site, which is the same URL used by the web player.

Requirements: Android 7.0 (API 24) or newer and Android Gradle Plugin 8.x, plus Kotlin 2.x if your app uses Kotlin. Works with Kotlin and Java, Views and Jetpack Compose.

1
Add the dependency

The SDK is published on Maven Central. Add it to the dependencies in your app module’s build.gradle.kts (or build.gradle):
app/build.gradle.kts
```
dependencies {
    implementation("io.github.instaread-co:sdk:1.+")
}
```
Using Jetpack Compose? Also add io.github.instaread-co:sdk-compose:1.+.
2
Request notification permission on Android 13 and above

Without this permission, the lock-screen media controls will not appear. Audio playback itself continues either way.
Activity
```
if (Build.VERSION.SDK_INT >= 33) {
    ActivityCompat.requestPermissions(
        this,
        arrayOf(Manifest.permission.POST_NOTIFICATIONS),
        0
    )
}
```

Configure the SDK once at app start

In your Application class, or in your main Activity if your app has none. Replace yourslug with your Instaread publication name.

Application class

import co.instaread.sdk.InstareadPlayer

class MyApp : Application() {
    override fun onCreate() {
        super.onCreate()
        InstareadPlayer.configure(this, "yourslug")
    }
}

Or in your main Activity

import co.instaread.sdk.InstareadPlayer

class MainActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)
        InstareadPlayer.configure(application, "yourslug")
    }
}

The first argument is your app’s Application: this inside your Application class, application inside an Activity. If you are creating a new Application class, register it in your AndroidManifest.xml with android:name=".MyApp" on the <application> tag.

Using Java? Call the SDK through InstareadPlayer.INSTANCE:

Java

import co.instaread.sdk.InstareadPlayer;

// In your Application class; use getApplication() inside an Activity
InstareadPlayer.INSTANCE.configure(this, "yourslug");

Add the player to your article screen

We recommend placing it at the top, so that the audio player appears immediately after the article heading and before the article text.

Views

import co.instaread.sdk.InstareadPlayerView

val player = InstareadPlayerView(context, articleUrl = "https://yoursite.com/your-article")
container.addView(player)

Jetpack Compose

import co.instaread.sdk.compose.InstareadPlayer

InstareadPlayer(articleUrl = "https://yoursite.com/your-article")

Java (Views)

import co.instaread.sdk.InstareadPlayerView;

InstareadPlayerView player = new InstareadPlayerView(context, "https://yoursite.com/your-article");
container.addView(player);

Important: please ensure that articleUrl points to the article’s own page URL on your site, which is the same URL used by the web player.

Requirements: Flutter 3.24 or newer. iOS 13+. Android 7.0 (API 24)+ with Kotlin 2.x and Android Gradle Plugin 8 or newer. One package covers both platforms. The native iOS and Android SDKs come with it.

1
Add the package

Add the SDK from pub.dev:
Terminal
```
flutter pub add instaread_sdk
```
2
Platform-specific setup

These are the platform-specific edits in the entire integration.

iOS

To enable background audio playback (so that audio continues playing when the app is in the background or the screen is locked), add the following configuration to your Info.plist:
ios/Runner/Info.plist
```
<key>UIBackgroundModes</key>
<array>
    <string>audio</string>
</array>
```
Android

Request notification permission on Android 13 and above. Without this permission, the lock-screen media controls will not appear. Using the permission_handler package:
main.dart
```
import 'dart:io' show Platform;
import 'package:permission_handler/permission_handler.dart';

// e.g. in main(), right after InstareadPlayer.configure(...)
if (Platform.isAndroid) {
  Permission.notification.request();
}
```

Configure the SDK once at your app’s root

Same code on iOS and Android. Replace yourslug with your Instaread publication name.

main.dart

import 'package:instaread_sdk/instaread_sdk.dart';

void main() {
  // Before anything renders
  InstareadPlayer.configure('yourslug');
  runApp(const MyApp());
}

4
Add the player to your article screen

We recommend placing it at the top, so that the audio player appears immediately after the article heading and before the article text.
article_screen.dart
```
import 'package:instaread_sdk/instaread_sdk.dart';

InstareadPlayerView(articleUrl: article.canonicalUrl)
```
Important: please ensure that articleUrl points to the article’s own page URL on your site, which is the same URL used by the web player.

That’s the whole integration. The player sizes itself, and the mini player appears on its own. Everything below is optional.

Reference

Configuration options and functions, for when you need more than the basics.

Configuration options

All configuration options are optional. When a value is not provided, the SDK uses your publication’s configured setting, followed by the SDK default.

All options

InstareadPlayer.configure('yourslug', {
  miniPlayerEnabled: true,
  miniPlayerBottomOffset: 49,
  playerType: 'compact',
  dark: true,
  singlePlayerMode: true,
});

All options

InstareadPlayer.configure(
    publication: "yourslug",
    miniPlayerEnabled: true,
    miniPlayerBottomOffset: 49,
    playerType: .compact,
    dark: true,
    singlePlayerMode: true
)

All options

import co.instaread.sdk.InstareadPlayerType

InstareadPlayer.configure(
    this,
    "yourslug",
    miniPlayerEnabled = true,
    miniPlayerBottomOffset = 56,
    playerType = InstareadPlayerType.COMPACT,
    dark = true,
    singlePlayerMode = true,
)

All options

InstareadPlayer.configure(
  'yourslug',
  miniPlayerEnabled: true,
  miniPlayerBottomOffset: 56,
  playerType: InstareadPlayerType.compact,
  dark: true,
  singlePlayerMode: true,
);

miniPlayerEnabled

Controls whether the floating mini player is displayed.Default: true

miniPlayerBottomOffset

The height of your app’s bottom UI, so the mini player can be positioned above it. See Mini player position.Default: 50

playerType

The inline player design: acoustic, compact or rectangular. See Player designs.Default: acoustic

dark

Enables the dark player theme.Default: false

singlePlayerMode

For apps with their own audio player. If only one player should be on screen at a time, set it to true and use onPlaybackStarted and stop(), as shown in Only if your app has its own audio player. To keep both players, leave it out and set miniPlayerBottomOffset high enough that the Instaread mini player sits above yours.Default: false

Functions

This is the whole public API. There is no client instance to create or pass between screens.

InstareadPlayer.configure(slug, options?)

Call once at app start with your publication name and any options. Calling it again replaces the whole configuration, so pass every option you use each time.

<InstareadPlayerView articleUrl />

The inline player for one article. It manages its own height: zero while there is nothing to display, a loading state while loading, then the player.

InstareadPlayer.onPlaybackStarted

Called when the Instaread player starts playing, so you can pause or close your own player. Requires singlePlayerMode.

InstareadPlayer.stop()

Closes the Instaread mini player. Call it when your own audio starts playing. Requires singlePlayerMode.

Mini player position

Use miniPlayerBottomOffset to move the mini player up, so it sits above your app’s bottom bar. If you leave it out, it defaults to 50, in the same units as your React Native styles (points on iOS, dp on Android).

Mini player offset

InstareadPlayer.configure('yourslug', { miniPlayerBottomOffset: 49 });

Mini player offset

InstareadPlayer.configure(publication: "yourslug", miniPlayerBottomOffset: 49)

Mini player offset

InstareadPlayer.configure(this, "yourslug", miniPlayerBottomOffset = 56)

Mini player offset

InstareadPlayer.configure('yourslug', miniPlayerBottomOffset: 56);

Only if your app has its own audio player

If your app plays its own audio and the two players should never play simultaneously, enable single-player mode and connect the handoff between the two players.

Single-player mode

InstareadPlayer.configure('yourslug', { singlePlayerMode: true });

// Instaread started playing → pause or close your player
InstareadPlayer.onPlaybackStarted = () => {
  myPlayer.pause();
};

// Your player started playing → close Instaread's mini player
myPlayer.onStartedPlaying(() => {
  InstareadPlayer.stop();
});

Single-player mode

InstareadPlayer.configure(publication: "yourslug", singlePlayerMode: true)

// Instaread started playing → pause or close your player
InstareadPlayer.onPlaybackStarted = {
    myPlayer.pause()
}

// Your player started playing → close Instaread's mini player (on the main thread)
myPlayer.onStartedPlaying {
    InstareadPlayer.stop()
}

Single-player mode

InstareadPlayer.configure(this, "yourslug", singlePlayerMode = true)

// Instaread started playing → pause or close your player
InstareadPlayer.onPlaybackStarted = {
    myPlayer.pause()
}

// Your player started playing → close Instaread's mini player
// e.g. with ExoPlayer or Media3, in your Player.Listener:
override fun onIsPlayingChanged(isPlaying: Boolean) {
    if (isPlaying) InstareadPlayer.stop()
}

Java

InstareadPlayer.INSTANCE.configure(this, "yourslug", null, null, null, null, true);

// Instaread started playing → pause or close your player
InstareadPlayer.INSTANCE.setOnPlaybackStarted(() -> {
    myPlayer.pause();
    return Unit.INSTANCE; // import kotlin.Unit
});

// Your player started playing → close Instaread's mini player
InstareadPlayer.INSTANCE.stop();

Single-player mode

InstareadPlayer.configure('yourslug', singlePlayerMode: true);

// Instaread started playing → pause or close your player
InstareadPlayer.onPlaybackStarted = () {
  myPlayer.pause();
};

// Your player started playing → close Instaread's mini player
myPlayer.onStartedPlaying(() {
  InstareadPlayer.stop();
});

Connect stop() to the event where your own audio actually begins playing, not only to your Play button. Playback can also start from a full-screen player, a track list or the lock screen.

Want to keep both players on screen instead? Leave singlePlayerMode out and set miniPlayerBottomOffset high enough that the Instaread mini player sits above your own player.

Player designs

Select a design using the playerType configuration: 'acoustic', 'compact' or 'rectangular'.

Acoustic is the default. See all three live in the design studio →

For custom designs, please contact us →

Additional resources

Usage, configuration options and troubleshooting are also available on the package page: @instaread-co/react-native-instaread-sdk on npm →

Questions about your integration? Talk to us →

Built for your developers.

Mobile SDK

Install the package

Platform-specific setup

Configure the SDK once at your app’s root

Add the player to your article screen

Add the Swift package

Enable background audio playback

Configure the SDK once at app start

Add the player to your article screen

Add the dependency

Request notification permission on Android 13 and above

Configure the SDK once at app start

Add the player to your article screen

Add the package

Platform-specific setup

Configure the SDK once at your app’s root

Add the player to your article screen

Reference

API Coming soon

MCP Coming soon