pusher_beams

Pusher Beams for Flutter

Official Flutter Plugin for Pusher Beams using Pigeon for platform plugin interface and Federated Plugin Architecture.

• Dart >= 2.12.x
• Flutter >= 2.x.x

Table of Contents

• Architecture
• Flutter Support
• Platform Support
  • Web Support
  • Mobile Support
• Example
• Prerequisites
  • Android Additional
  • iOS Additional
• Installation
• Initialization
• API Reference
• Contributing
  • Developing Environment
  • Running the tests
• License

Architecture

This plugin was developed based on the Federated Plugin Architecture, following packages are included in the plugin:

• pusher_beams: This is intended to be the main or app-facing package. You must install this package in order to use it.
• pusher_beams_platform_interface: This is the platform package interface that glues pusher_beams and platform packages.
• pusher_beams_android: This is a platform package which implements Android code.
• pusher_beams_ios: This is a platform package which implements the iOS code
• pusher_beams_web: This is a platform package which implements the Web code.

Flutter Support

This is the comparison table of functions implemented within this plugin according to the native libraries. (Android, iOS, Web)

	iOS	Android	Web
addDeviceInterest	✅	✅	✅
clearAllState	✅	✅	✅
clearDeviceInterests	✅	✅	✅
getDeviceInterests	✅	✅	✅
onInterestChanges	✅	✅	⬜️
onMessageReceivedInTheForeground	✅	✅	⬜️
getInitialMessage	✅	✅	⬜️
removeDeviceInterest	✅	✅	✅
setDeviceInterests	✅	✅	✅
setUserId	✅	✅	⬜️
start	✅	✅	✅
stop	✅	✅	✅

Platform Support

This plugin supports Web, Android and iOS platforms.

Web Support

• Chrome (mobile & desktop)
• Safari (mobile & desktop)
• Edge (mobile & desktop)
• Firefox (mobile & desktop)

See Web FAQ

Mobile Support

• iOS 10 and above
• Android 4.4 and above (>= SDK Version 19)

Example

A fully example using this plugin can be found in this repository, implementing a basic use of most of the functionality included in this plugin.

See Example

Prerequisites

In order to work with this Flutter plugin you must have a Pusher Beams Account and already got an instanceId within your dashboard, you can Sign Up here.

Android Additional

• Firebase Account and a google-services.json (follow this guide). Do not initialize anything, this plugin just requires a google-services.json within your android/app folder.
• Enable Multidex (If your minSdkVersion is lower than 21)
• For Android 12 support,compileSdkVersion must be set to 31 (and if you use kotlin, use the 1.5.30 version)

iOS Additional

• Enable capabilities within your iOS app.
• Configure APNs in order to work with iOS platform.

Installation

To install this plugin within you Flutter application, you need to add the package into your pubspec.yaml.

    dependencies:
      pusher_beams: ^1.0.1

or with flutter pub

flutter pub add pusher_beams

There are some additional steps for some platforms.

Android

• Add this line inside your project-level build.gradle which is located at your android folder

  buildscript {
      // Your config...
      
      repositories {
          // Your repositories...
      }
  
      dependencies {
          // Your dependencies...
  
          // Add this line
          classpath 'com.google.gms:google-services:4.2.0'
      }
  }
  

• Now, on your app-level build.gradle you must include com.google.gms.google-services ( google-services.json must be already included within your app as it's a prerequisite). Just add this line at the end of your app-level build.gradle.

  apply plugin: 'com.google.gms.google-services'
  

Web

• Create a file called service-worker.js inside your web folder.
• That file must include the following line:

  importScripts("https://js.pusher.com/beams/service-worker.js");
  

• Now you must add this <script> tag inside and at the beginning of your <body> tag within the web/index.html file:

  <script src="https://js.pusher.com/beams/1.0/push-notifications-cdn.js"></script>
  

Initialization

If you already have done the prerequisites, now you can initialize Pusher Beams using the start method as soon as possible (Preferable inside the main function).

void main() async {
  // Some initial code
  
  await PusherBeams.instance.start('YOUR INSTANCE ID');
  
  runApp(MyApp());
}

Ensure the bindings are initialized, you can do this by adding the following line inside your main function before you start this plugin.

void main() async {
  // Some initial code

  WidgetsFlutterBinding.ensureInitialized(); // Add this line
  await PusherBeams.instance.start('YOUR INSTANCE ID');

  runApp(MyApp());
}

Overall, that's all! ✨ Now you can use the methods described in the API Reference.

API Reference

If you want to see the API reference in-depth, you may want to see the Official API Reference from pub.dev.

Contributing

In order to contribute you must first read how to develop flutter plugins, this is the basic knowledge to start.

This repository is following git flow branching model, so in order to contribute, once you fork this project, you must create a fix/ or feature/ branch, which will be pull requested from you once it's ready.

Commits follows the conventional commits standard, which scopes are the follow:

• pusher_beams: For pusher_beams code commits.
• web: For pusher_beams_web code commits.
• ios: For pusher_beams_ios code commits.
• android: For pusher_beams_android code commits.
• interface: For pusher_beams_platform_interface code commits.

So, in order to commit something you must use a commit message like below:

feat(android): i did something to android code :0

Developing Environment

• Flutter >= 2.x.x (running flutter doctor will check if everything is good to start)
• To contribute on packages/pusher_beams_ios you must be in MacOS and Xcode must be installed

Running The Tests

There's two major tests, our app-facing package test which is run as Integration Test and our platform-interface package test run as Unit Test

Integration Tests

For integration tests, we use the example app provided in packages/pusher_beams/example. In order to run the integration tests you must complete the prerequisites in the example app which is...

• You already registered into Pusher Beams platform.
• You already have a Firebase Account linked with Pusher Beams
• The packages/pusher_beams/example app is already set up and firebase is initialized.

If you already double-check the list above, then you must replace the constant instanceId located on packages/pusher_beams/example/integration_test/pusher_beams_test.dart with a real one from Pusher Beams.

// Code...

const instanceId = 'your-instance-id'; // Replace this with a real instanceId

// More Code...

So that's all! you can now run the integration test with the following command on the example app path (packages/pusher_beams/example):

flutter test integration_test

And for web (Do not forget to read this):

flutter drive \
  --driver=test_driver/integration_test.dart \
  --target=integration_test/pusher_beams_test.dart \
  -d web-server

Unit Tests

In order to run unit tests for packages/pusher_beams_platform_interface you must be in the directory and run the following:

flutter test

Pigeons

As this plugin platform interface is generated by Pigeon and if you modified the file messages.dart from packages/pusher_beams_platform_interface package, in order to generate a new MethodChannel interface you must run the following command on path packages/pusher_beams_platform_interface:

make

After this command you must go to packages/pusher_beams_platform_interface/lib/method_channel_pusher_beams.dart and extends the class PusherBeamsApi with PusherBeamsPlatform like below:

class PusherBeamsApi extends PusherBeamsPlatform {
  // Pigeon Generated Class Code
}

This will require you to change the methods onInterestChanges and setUserId parameter arg_callbackId to type dynamic in order to accomplish PusherBeamsPlatform definition like below:

  // Class code...
  Future<void> onInterestChanges(dynamic arg_callbackId) async {
    // onInterestChanges generated function code...
  }

  Future<void> setUserId(String arg_userId, BeamsAuthProvider arg_provider, dynamic arg_callbackId) async {
    // setUserId generated function code...
  }
  // More class code...

License

Copyright (c) 2015 Pusher Ltd. See LICENSE for details.