AMPER Channels – powiadomienia w czasie rzeczywistym

AMPER Channels to usługa powiadomień w czasie rzeczywistym, zbudowana na Socket.IO. Serwer AMPER WS publikuje w niej zdarzenia (nowe zamówienie, ruch magazynowy, nowy post na ścianie, rekomendacje produktów), a aplikacje AMPER – panel administracyjny, sklep B2B, aplikacje mobilne – nasłuchują ich i odświeżają widok bez przeładowania.

Adres usługi: https://channels.ampli-solutions.com (w instalacjach dedykowanych adres może być inny – ustawienie CHANNELS_URL serwera AMPER WS).

Usługa nie ma API HTTP. Cała komunikacja odbywa się przez połączenie Socket.IO.

Przestrzenie (namespaces)

Połączenie

Klient łączy się z wybraną przestrzenią i w danych uwierzytelniających (auth) przekazuje:

Przykład (przeglądarka, pakiet socket.io-client w wersji 4):

import { io } from 'socket.io-client';

const socket = io('https://channels.ampli-solutions.com/document', {
  auth: {
    token: accessToken,                  // access_token z POST /auth/
    amperCompanyAssigned: companyName,   // amper-company-assigned z POST /auth/
  },
});

socket.on('connect', () => {
  // dołączenie do pokoju z nowymi zamówieniami instalacji
  socket.emit('room', `${companyName}:new-orders`);
});

socket.on('hello', (message) => console.log(message)); // potwierdzenie dołączenia do pokoju

socket.on('new-order', (data) => {
  console.log(data.title, data.message, data.url);
});

Token jest sprawdzany przy nawiązywaniu połączenia. Przy każdym ponownym łączeniu (np. po zerwaniu połączenia) przekaż aktualny, nieprzeterminowany token.

Pokoje

Zdarzenia trafiają do pokoi (rooms). Nazwa pokoju zaczyna się od identyfikatora instalacji (<firma> = amperCompanyAssigned), a klient może dołączyć tylko do pokoi własnej instalacji – zdarzeniem room z nazwą pokoju. Serwer potwierdza dołączenie zdarzeniem hello.

W przestrzeni /amper-live klient może dołączyć wyłącznie do własnego pokoju użytkownika – prośby o inne pokoje są ignorowane.

Zdarzenia

/document

new-order – nowe zamówienie w instalacji:

{ "title": "Nowe zamówienie", "message": "Klient ABC złożył zamówienie nr 12345", "url": "https://..." }

adding-an-item – produkt dodany do dokumentu sprzedaży (np. w punkcie sprzedaży) i item-stock-movement – zmiana stanu po imporcie stanów z ERP:

{ "product_id": 101, "quantity": 5.0, "location_id": 3 }

Oba zdarzenia trafiają do pokoju magazynu <firma>:stock:location:<location_id>.

/kb-feed

{ "post_id": 15 }                                    // new-post
{ "post_id": 15, "comment_id": 87 }                  // new-comment
{ "post_id": 15, "reaction_id": 4, "comment_id": 87 } // new-reaction

Zdarzenia zawierają tylko identyfikatory – treść posta, komentarza lub reakcji aplikacja pobiera z AMPER WS.

/amper-live

item-applied-promotion – do produktu w koszyku użytkownika została zastosowana promocja:

{
  "user_keycloak_id": "26259ede-...",
  "cart_line_id": 5521,
  "product": { "id": 101, "name": "...", "short_code": "426684" },
  "promotion": { "id": 999, "name": "Letnia wyprzedaż", "description": "...", "default_image": null }
}

product-recommendations – rekomendacje produktów po dodaniu produktu do koszyka:

{
  "user_keycloak_id": "26259ede-...",
  "added_product": { ... },
  "recommendations": [ { ... }, { ... } ]
}

Produkty mają format listy produktów sklepu B2B.

Kto publikuje zdarzenia

Zdarzenia publikuje serwer AMPER WS, korzystając z własnego konta technicznego. Aplikacje klienckie tylko ich nasłuchują.

Po stronie serwera AMPER WS usługę włącza ustawienie AMPER_CHANNELS_ENABLED.