NgPostMessenger

Lightweight service for safe communication between Window objects with Angular

Table of contents

1. Getting Started
2. Supporting
3. Installation instructions
4. Usage
5. Options
6. Compatibility
7. Contributing
8. License

Getting Started

ng-post-messenger handles safe communications between Window objects on Angular applications.

The library is based on the Window.postMessage() api. Information about compatibility and other related resources are available here: https://developer.mozilla.org/docs/Web/API/Window/postMessage

Supporting

ng-post-messenger is an Open Source (MIT Licensed) project started to solve specific problems for Aicof applications. All help and suggestions are appreciated!

Installation instructions

Install ng-post-messenger from npm:

npm install ng-post-messenger --save

(optional) Add needed package to NgModule imports to customize the service configuration

import {NgModule} from '@angular/core'; 
import {NgPostMessageModule} from 'ng-post-messenger';

@NgModule({
  ...
  imports: [
    NgPostMessageModule.forRoot({
          maxSynRetry: 10,
          synRetryPeriod: 1000,
          defaultTargetOrigin: '*',
        }),
    ...
    ]
  ...
})

Usage

To use NgPostMessage functionality inject the NgPostMessageService after importing NgPostMessageModule in your angular module.

NgPostMessageService.connect(receiver, options)

Tries to start a safe connection to the specified Window object. Emits after the connection is established.

import {Injectable} from '@angular/core';
import {NgPostMessageService} from 'ng-post-messenger';

@Injectable()
export class MyService {
  ...
  constructor(postMessage: NgPostMessageService) {
      postMessenger.connect(receiverWindow).subscribe(() => {
          console.log('connection with receiverWindow is established and secure');
      });
  }
  ...
}

NgPostMessageService.send(receiver, payload)

Sends a message to the specified Window.

import {Injectable} from '@angular/core';
import {NgPostMessageService} from 'ng-post-messenger';

@Injectable()
export class MyService {
  ...
  constructor(postMessenger: NgPostMessageService) {
    postMessenger.connect(receiverWindow).subscribe(() => {
      postMessenger.send(receiverWindow, {test: 'Hello my receiverWindow!'});
    });
  }
  ...
}

NgPostMessageService.listen(sender)

Starts listening to the specified sender.

import {Injectable} from '@angular/core';
import {NgPostMessageService} from 'ng-post-messenger';

@Injectable()
export class MyService {
  ...
  constructor(postMessenger: NgPostMessageService) {
    postMessenger.listen(senderWindow).subscribe(message => {
        console.log('[senderWindow] message', message);
    });
  }
  ...
}

Security Note

The native postMessage() api lacks the ability to check if a receiver is ready. To alleviate this problem, the connect method should be used before sending any message. NgPostMessage will take care of handling an 'handshake' between the two parts making sure that, at the time of connection, both ends are ready.

Options

Notes:

• The default options can be assigned with the NgPostMessageModule.forRoot(options) import.
• It is possible to use specific options, ignoring the defaults, following the documentation of the pertinent functions.

| Global | Type | Default value | Values | Description | | :------------------ | :------------ | :--------------- | :--------------------------------------------------------------------------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | maxSynRetry | number | 10 | time in milliseconds | Number of connection retries | | synRetryPeriod | number | 1000 | positive integer number | Time before retrying a failed connection attempt | | defaultTargetOrigin | string | '/' | origin of the current application | The origin of the window that sent the message (consult the official postMessage() documentation for details) | behaviour of tooltip |

How to build for development

First time:

• clone repository
• npm install
• npm run build

Compatibility

The only dependency is Angular. All the angular version from the 7.x.x to 9.x.x.

Contributing

All contributions are welcome! Both coding and helping others with troubleshooting!

License

MIT

Contributors

Main contributors:

• Fabio Baglione (GitHub, Linkedin)
• Riccardo Perra (GitHub, Linkedin)