expo-instagram-stories

A React Native/Expo module for sharing content to Instagram Stories. This package enables your app to share background and sticker assets (along with optional gradient colors) via Instagram’s native sharing functionality on both iOS and Android.

Note: This module requires a Facebook App ID when sharing content. On iOS, the module leverages a custom URL scheme and pasteboard to launch Instagram, while Android uses implicit intents.

Features

• Native Sharing: Supports background and sticker assets using Instagram’s native share-to-stories feature.
• Expo Config Plugin: Automatically configures your iOS project (Info.plist) to include the required URL scheme.
• Robust API: Provides error checking and data-type conversion to ensure image data is available in a usable format.
• Platform Support:
  • iOS: Uses a custom URL scheme (instagram-stories://share) along with pasteboard for image data.
  • Android: Utilizes implicit intents (action: com.instagram.share.ADD_TO_STORY) for sharing.

Installation

Install the package using npm or yarn:

npm install expo-instagram-stories
# or
yarn add expo-instagram-stories

If you are using an Expo managed workflow, run:

npx expo prebuild
or build with EAS Build.

Setup

iOS

The package uses an Expo config plugin to add the required URL scheme (instagram-stories) to your Info.plist. In your app.config.js or app.json, include the plugin:

module.exports = {
  expo: {
    name: "YourAppName",
    slug: "your-app-slug",
    ios: {
      // Your iOS configuration…
    },
    plugins: [
      "expo-instagram-stories"
    ]
  }
};

Android

For Android, ensure you have an environment that supports native modules (via Expo’s custom development client or bare workflow). Android configuration is managed by your project’s Gradle files. No extra setup in your package is required for Android.

Usage

Import and call the API function in your JavaScript code:

import { shareToInstagramStory } from 'expo-instagram-stories';

async function handleShare() {
  try {
    const result = await shareToInstagramStory({
      facebookAppId: '1234567', // Your Facebook App ID
      // Provide a local file URI or Base64 data URL for your background asset:
      backgroundAsset: 'file:///path/to/background.jpg',
      // Optional sticker asset:
      stickerAsset: 'file:///path/to/sticker.png',
      // Optional gradient colors (if not using an image asset for background):
      topBackgroundColor: '#33FF33',
      bottomBackgroundColor: '#FF00FF'
    });
    console.log('Share successful:', result);
  } catch (error) {
    console.error('Error sharing to Instagram Stories:', error);
  }
}

Native Module Details

iOS

The Objective‑C module (InstagramStoriesModule.m) uses the custom URL scheme instagram-stories://share and the pasteboard to send the following data:

facebookAppId: Your Facebook App ID.

backgroundImageData: NSData representing the background image (this can be a file URI or a Base64 data URL that is converted into NSData).

stickerImageData: Optional NSData representing the sticker image.

topBackgroundColor and bottomBackgroundColor: Optional hex string colors for the background gradient.

The module employs robust type-checking and returns error callbacks if required parameters are missing or if Instagram is not installed.

Android The Java module (InstagramStoriesModule.java) uses an implicit intent with the action com.instagram.share.ADD_TO_STORY. It extracts the following options:

facebookAppId: Your Facebook App ID.

backgroundAsset: URI for the background asset (e.g., image URI).

stickerAsset: Optional URI for the sticker asset.

topBackgroundColor and bottomBackgroundColor: Optional gradient colors.

It verifies that an Activity is available, sets the required intent extras, and opens Instagram if it’s installed. If Instagram isn’t available, the module can log errors or handle the situation gracefully.

Directory Structure

Your package is structured as follows:

expo-instagram-stories/
├── android/
│   └── src/main/java/com/aura/instagramstories/InstagramStoriesModule.java
├── ios/
│   └── InstagramStoriesModule.m
├── plugin/
│   └── withInstagramStories.js
├── index.js
├── package.json
└── README.md

Testing Locally

1. Linking:
   Include the package in a React Native or Expo project.

2. Configuration:
   Confirm that your project uses the Expo config plugin (via your app.config.js or app.json).

3. Build:
   Run npx expo prebuild (for managed workflow) or build your project in the bare workflow using your native build tools.

4. Deploy & Test:
   Deploy on a real device or simulator/emulator with Instagram installed and verify that sharing works as expected.

Contributing

Contributions are welcome! Please open issues for any bugs you find or submit pull requests with enhancements.

License

This project is licensed under the MIT License.

Feel free to modify or extend any section to match your project’s specific needs. Once you save this as README.md in your package root, you can test the module locally by linking it in an Expo or React Native project. Happy coding!