ng-post-messenger

https://www.npmjs.com/package/ng-post-messenger
Admin
ng-post-messenger is a lightweight Angular service for safe communication between Window objects...
Tokens:4,389
Snippets:60
Trust Score:9.6
Update:6 months ago
Show doc for...
Tokens:
Raw
### Installation

Source: https://www.npmjs.com/package/ng-post-messenger?activeTab=versions

Instructions on how to install the ng-post-messenger package using npm.

```APIDOC
## Installation

Install `ng-post-messenger` from `npm`:

```bash
npm install ng-post-messenger --save
```

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

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

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

--------------------------------

### Install ng-post-messenger

Source: https://www.npmjs.com/package/ng-post-messenger

Use npm to install the package as a dependency.

```bash
npm install ng-post-messenger --save
```

--------------------------------

### Installation

Source: https://www.npmjs.com/package/ng-post-messenger?activeTab=dependencies

Instructions on how to install the ng-post-messenger package using npm and configure it within your Angular module.

```APIDOC
## Installation

### Install from npm
```bash
npm install ng-post-messenger --save
```

### Configure NgModule
(Optional) Add `NgPostMessageModule` to your NgModule imports to customize service configuration.

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

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

--------------------------------

### Development Build Script

Source: https://www.npmjs.com/package/ng-post-messenger?activeTab=versions

Commands to clone the repository, install dependencies, and build the project for development. This is typically done after cloning the repository.

```bash
npm install
npm run build
```

--------------------------------

### NgPostMessageService.listen

Source: https://www.npmjs.com/package/ng-post-messenger

Starts listening for incoming messages from a specific sender Window.

```APIDOC
## listen(sender)

### Description
Starts listening to the specified sender for incoming messages.

### Parameters
#### Path Parameters
- **sender** (Window) - Required - The Window object to listen to.

### Response
- **Observable** - Emits incoming messages from the specified sender.
```

--------------------------------

### NgPostMessageService.listen

Source: https://www.npmjs.com/package/ng-post-messenger?activeTab=readme

Starts listening for incoming messages from a specific sender.

```APIDOC
## listen(sender)

### Description
Starts listening to the specified sender.

### Parameters
- **sender** (Window) - Required - The Window object to listen to.

### Response
- **Observable** - Emits messages received from the sender.
```

--------------------------------

### Connect to a Window object

Source: https://www.npmjs.com/package/ng-post-messenger

Establish a secure connection to a target window before attempting to send messages.

```typescript
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');
      });
  }
  ...
}
```

--------------------------------

### Options Configuration

Source: https://www.npmjs.com/package/ng-post-messenger?activeTab=dependencies

Details on the available options for configuring the `NgPostMessageModule` and their default values.

```APIDOC
## Options

Global options can be set using `NgPostMessageModule.forRoot(options)`.

| 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) |
```

--------------------------------

### NgPostMessageService Usage

Source: https://www.npmjs.com/package/ng-post-messenger?activeTab=dependencies

Demonstrates how to inject and use the `NgPostMessageService` for establishing connections, sending messages, and listening for incoming messages.

```APIDOC
## NgPostMessageService Usage

Inject the `NgPostMessageService` into your Angular components or services after importing `NgPostMessageModule`.

### Connect to a Window

Establishes a secure connection to a specified Window object. Emits an event once the connection is successfully established.

```typescript
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');
      });
  }
}
```

### Send a Message

Sends a message payload to a specified Window object.

```typescript
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!'});
    });
  }
}
```

### Listen for Messages

Starts listening for messages from a specified sender Window.

```typescript
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);
    });
  }
}
```
```

--------------------------------

### NgPostMessageService.connect

Source: https://www.npmjs.com/package/ng-post-messenger?activeTab=readme

Establishes a secure connection with a target Window object.

```APIDOC
## connect(receiver, options)

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

### Parameters
- **receiver** (Window) - Required - The target Window object to connect to.
- **options** (Object) - Optional - Configuration options for the connection attempt.
```

--------------------------------

### Configuration Options

Source: https://www.npmjs.com/package/ng-post-messenger?activeTab=versions

Details on the configuration options available for customizing the ng-post-messenger service, including default values and their purpose.

```APIDOC
## 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)  
```

--------------------------------

### Security Note

Source: https://www.npmjs.com/package/ng-post-messenger?activeTab=dependencies

Explanation of the security considerations and the role of the `connect` method in ensuring secure communication.

```APIDOC
## 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 a 'handshake' between the two parts, making sure that, at the time of connection, both ends are ready.
```

--------------------------------

### NgPostMessageService.connect

Source: https://www.npmjs.com/package/ng-post-messenger

Establishes a secure connection with a target Window object using a handshake mechanism.

```APIDOC
## connect(receiver, options)

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

### Parameters
#### Path Parameters
- **receiver** (Window) - Required - The target Window object to connect to.
- **options** (Object) - Optional - Configuration overrides for the connection.

### Response
- **Observable** - Emits when the connection is established and secure.
```

--------------------------------

### NgPostMessageService.connect

Source: https://www.npmjs.com/package/ng-post-messenger?activeTab=code

Establishes a secure connection to a specified Window object. This method should be used before sending messages to ensure the receiver is ready.

```APIDOC
## NgPostMessageService.connect(receiver, options)

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

### Method

`connect`

### Parameters

#### Path Parameters

None

#### Query Parameters

None

#### Request Body

None

### Request Example

```typescript
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');
      });
  }
  ...
}
```

### Response

#### Success Response (200)

An observable that emits when the connection is successfully established.

#### Response Example

(Observable emits upon successful connection)
```

--------------------------------

### NgPostMessageService.connect

Source: https://www.npmjs.com/package/ng-post-messenger?activeTab=versions

Establishes a secure connection to a specified Window object. This method should be used before sending messages to ensure the receiver is ready.

```APIDOC
## NgPostMessageService.connect(receiver, options)

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

### Method

`connect`

### Parameters

#### Path Parameters

None

#### Query Parameters

None

#### Request Body

None

### Request Example

```typescript
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');
      });
  }
  ...
}
```

### Response

#### Success Response (200)

Emits when the connection is successfully established.

#### Response Example

(No specific response body example provided, emits a success signal)
```

--------------------------------

### Configuration Options

Source: https://www.npmjs.com/package/ng-post-messenger?activeTab=code

Details on the configuration options available for customizing the ng-post-messenger service, including retry mechanisms and default target origins.

```APIDOC
## 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 Options

| Option Name | 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) |
```

--------------------------------

### Listen for messages

Source: https://www.npmjs.com/package/ng-post-messenger

Subscribe to incoming messages from a specific sender window.

```typescript
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);
    });
  }
  ...
}
```

--------------------------------

### Connect to a Receiver Window

Source: https://www.npmjs.com/package/ng-post-messenger?activeTab=versions

Inject NgPostMessageService and use the connect method to establish a secure connection with a receiver Window object. Subscribe to the observable to be notified when the connection is established.

```typescript
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');
      });
  }
  ...
}
```

--------------------------------

### Configure NgPostMessageModule

Source: https://www.npmjs.com/package/ng-post-messenger?activeTab=versions

Optionally, import NgPostMessageModule and configure its settings using forRoot(). This allows customization of connection retry parameters and default target origin.

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

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

--------------------------------

### Configure NgPostMessageModule

Source: https://www.npmjs.com/package/ng-post-messenger

Import the module into your NgModule and optionally provide configuration settings for connection retries and default origins.

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

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

--------------------------------

### Send a message to a Window

Source: https://www.npmjs.com/package/ng-post-messenger

Send a payload to a connected window using the NgPostMessageService.

```typescript
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!'});
    });
  }
  ...
}
```

--------------------------------

### Listen for Messages from a Sender Window

Source: https://www.npmjs.com/package/ng-post-messenger?activeTab=versions

Use the listen method of NgPostMessageService to subscribe to incoming messages from a specific sender Window. The callback function will receive the message payload.

```typescript
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);
    });
  }
  ...
}
```

--------------------------------

### NgPostMessageService.send

Source: https://www.npmjs.com/package/ng-post-messenger?activeTab=code

Sends a message payload to a specified Window object. It is recommended to establish a connection using `connect` before sending messages.

```APIDOC
## NgPostMessageService.send(receiver, payload)

> Sends a message to the specified Window.

### Method

`send`

### Parameters

#### Path Parameters

None

#### Query Parameters

None

#### Request Body

- **receiver** (Window) - The target window object to send the message to.
- **payload** (any) - The data to be sent. This can be any JSON-serializable object.

### Request Example

```typescript
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!'});
    });
  }
  ...
}
```

### Response

#### Success Response (200)

This method does not return a value directly upon sending. Success is indicated by the absence of errors during transmission.

#### Response Example

(No direct response, relies on successful transmission)
```

--------------------------------

### NgPostMessageService.send

Source: https://www.npmjs.com/package/ng-post-messenger

Sends a message payload to a previously connected Window object.

```APIDOC
## send(receiver, payload)

### Description
Sends a message to the specified Window. Should be called after a successful connection.

### Parameters
#### Path Parameters
- **receiver** (Window) - Required - The target Window object.
- **payload** (any) - Required - The data to be sent.
```

--------------------------------

### Send a Message to a Receiver Window

Source: https://www.npmjs.com/package/ng-post-messenger?activeTab=versions

After establishing a connection, use the send method of NgPostMessageService to transmit a payload to the specified receiver Window. Ensure a connection is made before sending.

```typescript
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!'});
    });
  }
  ...
}
```
Tokens:
Raw