instaread_sdk 1.0.3

Instaread audio player for Flutter apps on iOS and Android. Wraps the native Instaread iOS and Android SDKs.

instaread_sdk

Audio player for article screens in Flutter, supporting iOS and Android.

The SDK provides the Instaread Audio Player inside your Flutter app, including background playback, lock-screen controls, and a floating mini player.

The same Dart API works on both platforms. The native Instaread iOS and Android SDKs are included, so no additional SDK download is required.

---

Requirements

Platform	Requirement
Flutter	3.24 or newer
iOS	13.0+
Android	API 24 (Android 7.0)+, Kotlin 2.x, Android Gradle Plugin 8.x+
iOS Background Audio	UIBackgroundModes with audio
Android Notifications	POST_NOTIFICATIONS on Android 13+
Network	HTTPS access to player.instaread.co and player-api.instaread.co

The SDK has been built and tested with Flutter 3.47.6, with both Swift Package Manager and CocoaPods on iOS.

---

1. Add the package

Add the SDK from pub.dev:

flutter pub add instaread_sdk

Or add it to the dependencies section of your app's pubspec.yaml yourself and run flutter pub get:

dependencies:
  instaread_sdk: ^1.0.1

Nothing else needs to be installed. On iOS, Flutter links the SDK through Swift Package Manager or CocoaPods automatically, whichever your app uses.

---

2. Complete the platform-specific setup

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

iOS

Enable background audio playback

To allow audio to continue playing when the app is in the background or the device screen is locked, add the following configuration to ios/Runner/Info.plist:

<key>UIBackgroundModes</key>
<array>
    <string>audio</string>
</array>

This configuration belongs to your application and must be added manually. Without it, playback will stop when the device screen is locked.

After adding this configuration, rebuild the app.

---

Android

A. Check the minimum Android version

The SDK needs Android 7.0 (API 24) or newer. If android/app/build.gradle (or build.gradle.kts) sets minSdk lower than 24, set it to 24:

defaultConfig {
    minSdk = 24
}

New Flutter projects already use 24.

B. Request notification permission on Android 13 and above

Request POST_NOTIFICATIONS permission from your application. Flutter has no built-in API for this; the permission_handler package is the usual choice:

import 'dart:io' show Platform;
import 'package:permission_handler/permission_handler.dart';

if (Platform.isAndroid) {
  await Permission.notification.request();
}

This permission is required for the notification and lock-screen media controls to appear.

Audio playback itself will continue without this permission.

The SDK declares POST_NOTIFICATIONS, FOREGROUND_SERVICE and FOREGROUND_SERVICE_MEDIA_PLAYBACK in its own manifest, so nothing needs to be added to your AndroidManifest.xml.

---

3. Configure the SDK once at your app's root

Initialize the SDK once when your application starts, before anything renders — at the top of main():

import 'package:instaread_sdk/instaread_sdk.dart';

void main() {
  InstareadPlayer.configure('yourslug');
  runApp(const MyApp());
}

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

The publication name should be provided in the same format as your partner/publication name. The SDK normalizes it to the publication slug used by Instaread.

---

4. Add the player to your article screen

Add InstareadPlayerView wherever you want the audio player to appear on 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.

import 'package:instaread_sdk/instaread_sdk.dart';

SingleChildScrollView(
  child: Column(
    children: [
      Text(article.title),
      InstareadPlayerView(articleUrl: article.canonicalUrl),
      Text(article.body),
    ],
  ),
)

Important

articleUrl must point to the article's own page URL on your website.

It should be the same article URL used by the Instaread web player.

The player automatically manages its own size:

• It fills the width it is given.
• It has zero height while there is nothing to display.
• It shows a loading state while the player is loading.
• It then displays the player or the appropriate audio state.
• It does not scroll independently, so it should be placed inside your article's scrolling widget.

Use Padding or Align around it for placement. Its width and height are not set by the app.

That's the basic integration. There is no client instance to create or pass between screens. All InstareadPlayerView widgets and the mini player share the SDK's internal player state.

---

5. Optional: Configure the player

The basic configuration only requires your publication name:

InstareadPlayer.configure('yourslug');

You can also provide optional configuration:

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

All configuration options are optional.

When a configuration value is not provided, the SDK uses the publication's configured setting, followed by the SDK default.

Calling configure again replaces the whole configuration, so pass every option you use each time.

Configuration options

Option	Default	Description
miniPlayerEnabled	true	Controls whether the floating mini player is displayed.
miniPlayerBottomOffset	50	The height of your app's bottom UI so the mini player can be positioned above it.
playerType	acoustic	The inline player design: acoustic, compact, or rectangular.
dark	false	Enables the dark player theme.
singlePlayerMode	false	Enables coordination between the Instaread Player and your app's own audio player.

Player view options

Parameter	Description
articleUrl	Required. The article's own page URL on your website.
publication	Overrides the publication for this one player. Leave it out to use the one passed to configure.
dark	Overrides the dark theme for this one player. Leave it out to use the value passed to configure.
onReady	Called once the player has shown something for this article.
onError	Called once if nothing has shown 15 seconds after the player was created — typically a wrong publication or no network.

---

6. Configure the 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 Flutter layout.

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

---

7. Optional: Integrate with your existing audio player

If your app already has its own audio player and the two players should never play simultaneously, enable singlePlayerMode.

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

Then connect the two players:

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

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

The important part is to connect InstareadPlayer.stop() to the event where your own audio actually begins playing, rather than only to the Play button. Playback can also start from a full-screen player, track list, lock screen, or another control.

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.

How single-player mode works

• When Instaread starts playing, onPlaybackStarted is called so you can pause or close your own player.
• When your player starts playing, call InstareadPlayer.stop() to close the Instaread mini player.
• These callbacks only take effect when singlePlayerMode is enabled.
• Stopping one player does not automatically start the other, so there is no callback loop.

---

8. Player designs

The SDK supports three inline player designs:

Acoustic	Compact	Rectangular	Custom

Note: For custom designs, please contact us.

Select a design using the playerType configuration:

InstareadPlayer.configure('yourslug', playerType: InstareadPlayerType.compact);

Supported values are:

InstareadPlayerType.acoustic
InstareadPlayerType.compact
InstareadPlayerType.rectangular

---

9. Privacy

The native iOS SDK includes Apple's PrivacyInfo.xcprivacy privacy manifest.

The SDK collects:

• An anonymous device identifier — a random UUID stored in the Keychain rather than the advertising ID.
• Playback interactions used for analytics and app functionality.

This information is not linked to user identity and is not used for tracking.

Your application's App Store privacy information and Google Play Data safety information remain your responsibility to configure.

---

License

Proprietary. See LICENSE.