webman/push

webman/push es un plugin gratuito para servidor de notificaciones que utiliza un modelo de suscripción en el cliente, es compatible con pusher y cuenta con numerosos clientes como JS, Android (java), iOS (swift), iOS (Obj-C), uniapp, .NET, Unity, Flutter, AngularJS, etc. El SDK de notificaciones para el backend es compatible con PHP, Node, Ruby, Asp, Java, Python, Go, Swift, entre otros. El cliente incluye latidos de corazón y reconexión automática al perder conexión, lo que hace que su uso sea muy simple y estable. Es adecuado para varios escenarios de comunicación en tiempo real como notificaciones de mensajes y chats.

El plugin incluye un cliente web js llamado push.js y un cliente uniapp llamado uniapp-push.js. Los clientes en otros lenguajes se pueden descargar en https://pusher.com/docs/channels/channels_libraries/libraries/.

Instalación

composer require webman/push

Cliente (javascript)

Incluir el cliente javascript

<script src="/plugin/webman/push/push.js"> </script>

Uso del cliente (canal público)

// Establecer conexión
var connection = new Push({
    url: 'ws://127.0.0.1:3131', // dirección websocket
    app_key: '<app_key, obtener de config/plugin/webman/push/app.php>',
    auth: '/plugin/webman/push/auth' // Autenticación para suscripción (solo para canales privados)
});
// Supongamos que el uid del usuario es 1
var uid = 1;
// El navegador escucha los mensajes en el canal user-1, es decir, los mensajes del usuario con uid 1
var user_channel = connection.subscribe('user-' + uid);

// Cuando hay un evento message en el canal user-1
user_channel.on('message', function(data) {
    // data contiene el contenido del mensaje
    console.log(data);
});
// Cuando hay un evento friendApply en el canal user-1
user_channel.on('friendApply', function (data) {
    // data contiene la información relacionada con la solicitud de amistad
    console.log(data);
});

// Supongamos que el ID del grupo es 2
var group_id = 2;
// El navegador escucha los mensajes en el canal group-2, es decir, los mensajes del grupo 2
var group_channel = connection.subscribe('group-' + group_id);
// Cuando hay un evento message en el grupo 2
group_channel.on('message', function(data) {
    // data contiene el contenido del mensaje
    console.log(data);
});

Consejo
En el ejemplo anterior, subscribe implementa la suscripción al canal, message y friendApply son eventos del canal. Los nombres de los canales y eventos son cadenas arbitrarias y no necesitan ser configurados previamente en el servidor.

Notificaciones del servidor (PHP)

use Webman\Push\Api;
$api = new Api(
    // Se puede usar config directamente bajo webman, en un entorno que no es webman, se deben escribir las configuraciones correspondientes manualmente
    'http://127.0.0.1:3232',
    config('plugin.webman.push.app.app_key'),
    config('plugin.webman.push.app.app_secret')
);
// Enviar un mensaje del evento message a todos los clientes suscritos al canal user-1
$api->trigger('user-1', 'message', [
    'from_uid' => 2,
    'content'  => 'Hola, este es el contenido del mensaje'
]);

Canales privados

En el ejemplo anterior, cualquier usuario puede suscribirse a la información a través de Push.js, lo que no es seguro si la información es sensible.

webman/push soporta suscripciones a canales privados, que tienen un prefijo private-. Por ejemplo

var connection = new Push({
    url: 'ws://127.0.0.1:3131', // dirección websocket
    app_key: '<app_key>',
    auth: '/plugin/webman/push/auth' // Autenticación para suscripción (solo para canales privados)
});

// Supongamos que el uid del usuario es 1
var uid = 1;
// El navegador escucha los mensajes en el canal privado private-user-1
var user_channel = connection.subscribe('private-user-' + uid);

Cuando el cliente se suscribe a un canal privado (canales que comienzan con private-), el navegador iniciará una solicitud ajax de autenticación (la dirección ajax es la configurada en el parámetro auth al crear un nuevo Push). El desarrollador puede determinar aquí si el usuario actual tiene permiso para escuchar este canal. Esto asegura la seguridad de la suscripción.

Para más sobre autenticación, consulta el código en config/plugin/webman/push/route.php.

Notificaciones del cliente

Los ejemplos anteriores muestran cómo el cliente suscribe a un canal y el servidor usa la API para enviar notificaciones. webman/push también permite que los clientes envíen mensajes directamente.

Importante
La notificación entre clientes solo es soportada para canales privados (cuyos nombres comienzan con private-), y los clientes solo pueden disparar eventos que comienzan con client-.

Ejemplo de un cliente enviando un evento

var user_channel = connection.subscribe('private-user-1');
user_channel.on('client-message', function (data) {
    // 
});
user_channel.trigger('client-message', {from_uid:2, content:"hola"});

Importante
El código anterior envía datos del evento client-message a todos los clientes que están suscritos a private-user-1 (los clientes que envían la notificación no recibirán los datos que enviaron).

webhooks

Los webhooks se utilizan para recibir ciertos eventos del canal.

Actualmente hay 2 eventos principales:

    1. channel_added
      Se activa cuando un canal pasa de tener ningún cliente en línea a tener clientes en línea, o se puede decir que es un evento de conexión.
    1. channel_removed
      Se activa cuando todos los clientes de un canal están desconectados, o se puede decir que es un evento de desconexión.

Consejo
Estos eventos son muy útiles para mantener el estado de conexión de los usuarios.

Importante
La dirección del webhook se configura en config/plugin/webman/push/app.php.
Consulta la lógica para manejar eventos de webhook en config/plugin/webman/push/route.php.
Las desconexiones breves causadas por la actualización de la página no deben considerarse como una desconexión, webman/push realizará un juicio de retraso, por lo que habrá un retraso de 1-3 segundos en los eventos de conexión/desconexión.

Proxy WSS (SSL)

No se puede utilizar la conexión ws bajo https, se debe usar una conexión wss. En tal caso, se puede usar nginx para hacer un proxy de wss, con una configuración similar a la siguiente:

server {
    # .... otras configuraciones omitidas ...

    location /app/<app_key>
    {
        proxy_pass http://127.0.0.1:3131;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "Upgrade";
        proxy_set_header X-Real-IP $remote_addr;
    }
}

Nota: el <app_key> en la configuración anterior se obtiene en config/plugin/webman/push/app.php.

Después de reiniciar nginx, usa la siguiente forma para conectar al servidor

var connection = new Push({
    url: 'wss://example.com',
    app_key: '<app_key, obtener de config/plugin/webman/push/app.php>',
    auth: '/plugin/webman/push/auth' // Autenticación para suscripción (solo para canales privados)
});

Importante

  1. La dirección de la solicitud debe comenzar con wss.
  2. No especifiques un puerto.
  3. Debe usar el nombre de dominio correspondiente al certificado ssl para la conexión.

Instrucciones de uso de push-vue.js

  1. Copia el archivo push-vue.js en el directorio del proyecto, por ejemplo: src/utils/push-vue.js.

  2. Inclúyelo en la página de Vue.



## Otras direcciones de cliente
`webman/push` es compatible con pusher, las direcciones para descargar clientes en otros lenguajes (Java, Swift, .NET, Objective-C, Unity, Flutter, Android, iOS, AngularJS, etc.) están disponibles en:
https://pusher.com/docs/channels/channels_libraries/libraries/