SDK: Expo plugin

Step 1: Install the packages

@pushly/push-sdk-expo applies the native configuration; @pushly/push-sdk-react-native provides the runtime SDK you import from. Install both.

Yarn

yarn add @pushly/push-sdk-expo @pushly/push-sdk-react-native

NPM

npm install --save @pushly/push-sdk-expo @pushly/push-sdk-react-native

Step 2: Adding plugin to Expo config

Step 2.1: Google Services

Add your google-services.json file to app directory.

Step 2.2: app.config.js

Add the plugin to your Expo config and provide the App Group ID, Android application ID (must match the package inside google-services.json), and the path to your google-services.json file:

app.config.js

export default {
  expo: {
    ...,
    plugins: [
      [
        '@pushly/push-sdk-expo',
        {
          ios: {
            nseTargetName: 'NotificationServiceExtension',
            nseBundleIdSuffix: '.NotificationServiceExtension',
            appGroupId: 'group.com.example.myapp.push',
            swiftVersion: '5.0',
          },
          android: {
            applicationId: 'com.example.myapp',
            googleServicesFile: './app/google-services.json',
            applyGoogleServicesPlugin: true,
          },
        },
      ],
    ],
  },
};

Property	Definition
ios.nseTargetName	User-defined name for NotificationServiceExtension. default: NotificationServiceExtension
ios.nseBundleIdSuffix	Bundle id suffix for NotificationServiceExtension. Value is appended to PRODUCT_BUNDLE_IDENTIFIER env var. default: .NotificationServiceExtension
ios.appGroupId	To ensure that the PushSDK can properly capture information the container should be named group.{app-bundle-id}.push.
ios.swiftVersion	Used to setup NotificationServiceExtension target in pbxproj file. default: 5.0
android.applicationId	Application ID used by Android application. Defaults to android.package from your Expo config.
android.googleServicesFile	Location of google-services.json file relative to the project root
android.applyGoogleServicesPlugin	Should google services plugin be applied in gradle. default: true

Run expo prebuild --clean (or use EAS Build/custom dev clients) to generate native projects with the Pushly setup applied.

Step 3: iOS Setup

Step 3.1: Install Pods

Within your <project_root>/ios directory run: bundle exec pod install

Step 3.2: Notification Service Extension

A Notification Service Extension is required to unlock full rich media and analytics tracking functionality, which this plugin installs for you during prebuild.

Use expo run:ios or an EAS build to ensure automatic NSE installation. If your project has a checked-in ios/ directory, expo prebuild will not regenerate it and EAS skips prebuild entirely. In that case, run npx expo prebuild --platform ios --clean so the extension is installed.

To verify the extension was installed in a build, inspect the IPA:

unzip -l YourApp.ipa | grep appex

This should list PlugIns/NotificationServiceExtension.appex. If it does not, the extension was never installed — confirm you are using a dev or EAS build and that prebuild ran.

Step 4: SDK Initialization

In your index.tsx or app.tsx file initialize the PushSDK using the example implementation code below.

Replace the REPLACE_WITH_SDK_KEY in the setConfiguration method with the SDK Key from the platform settings page.

index.tsx

...
import { PushSDK, LogLevel } from '@pushly/push-sdk-react-native';

export const App = () => {
    ...

    // We recommend initializing the PushSDK in a useEffect block
    // to prevent the application from attempting to invoke
    // PushSDK.setConfiguration() on each rerender
    React.useEffect(() => {
        PushSDK.setLogLevel(LogLevel.INFO);
        PushSDK.setConfiguration({ appKey: 'REPLACE_WITH_SDK_KEY' });

        PushSDK.showNativeNotificationPermissionPrompt().then(({ granted }) => {
            console.log(`Permissions granted: ${granted}`);
        });
    }, []);
    
    // The rest of the your app
    ...
};

Run your application on either an Android device or emulator (ensure the emulator has Google Play Store Services installed) or on an iOS device, if building for iOS, to make sure it builds correctly.

The code you added in the previous step will show the push permission dialog upon app open. This can be customized by using SDK methods to control when the dialog shows.

After accepting the dialog log into the platform and navigate to Notifications > Create Notification and send your first notification, targeting the appropriate Native: iOS or Native: Android channel, to your device.

Next Steps

Once you have confirmed the SDK is working properly you may continue to add additional optional functionality like:

• Handling notification opens / app links / deep linking

• Attaching attributes to a subscriber's profile

• Sending information about what content a subscriber interacts with