Implementace komunikačního snippetu

Tento návod vám umožní snadno integrovat službu pro interní komunikaci přímo do vašich webových stránek nebo aplikace. Uživatelé tak mohou komunikovat v kontextu konkrétních objednávek, faktur či jiných dokumentů, což zefektivňuje a zpřehledňuje výměnu informací.

PHP Knihovna

Pro snadnější integraci v PHP projektech jsme připravili knihovnu pro generování snippetů, která je dostupná na GitHubu a skrze Composer.

composer require stromcom/php-snippet

Krok 1: Vložení základního snippetu

Následující javascriptový kód je základním kamenem celé služby. Je potřeba ho vložit na všechny stránky, kde chcete, aby se zobrazovala vlákna s komentáři, nebo aby uživatelé dostávali upozornění na nové zprávy. Ideální je vložit tento kód do hlavičky vaší stránky, těsně před uzavírací tag </head>, nebo co nejdříve. Načítání probíhá asynchroně a je tudíž neblokující.

<script>
  (function(win, d, e, l, k, s) {
  var dl=l+'DL',c=function(s,n,a){n=n||s;(a?win[dl][n]=[]:null);win[l][s]=function(...p){a?win[dl][n].push(p):win[dl][n]=p;}},f=d.getElementsByTagName(e)[0],j=d.createElement(e);
  win[dl]=win[dl]||{};win[l]={};c('initUser','user');c('thread','threads',!0);c('conf');c('home',0,!0);
  ;j.async=true;j.dataset.type='stromcom';j.dataset.l=l;j.dataset.dl=dl;j.dataset.ck=k;j.dataset.cs=s;
  j.src = "https://cdn.stromcom.cz/loader.js?"+k;f.parentNode.insertBefore(j,f);
  })(window, document, 'script', "stromCom", "exampleOfClientKey", "exampleOfBearerToken");
</script>

Krok 2: Nastavení uživatele

Po vložení základního snippetu je nutné identifikovat aktuálně přihlášeného uživatele. To umožní našemu systému správně přiřazovat zprávy a notifikace. Tento kód vložte kamkoliv za základní snippet.

Základní minimální použití

Nejjednodušší způsob, jak inicializovat uživatele, je pomocí jeho unikátního kódu.

<script>
  stromCom.initUser({
    /**
     * Unique user code. Cannot be changed later. Max length 100. Allowed characters: [a-zA-Z0-9-_] (required)
     */
    "code": "1",

    /**
     * User display name (optional)
     */
    "name": "John Doe"
  });
</script>

Pokročilé se všemi vlastnostmi

Pro lepší uživatelský zážitek a funkčnost (například e-mailové notifikace) doporučujeme poskytnout co nejvíce informací.

<script>
  stromCom.initUser({
    /**
     * Unique user code. Cannot be changed later. Max length 100. Allowed characters: [a-zA-Z0-9-_] (required)
     */
    "code": "1",

    /**
     * User display name (optional)
     */
    "name": "John Doe",

    /**
     * Email address used for notifications (optional)
     */
    "emailAddress": "john.doe@example.com",

    /**
     * Avatar URL (optional)
     */
    "avatarURL": "https://gravatar.com/avatar/7100c67cd4376b3d44d7fd6360f2ee59?s=50&r=g&s=100&d=robohash"
  });
</script>

Krok 3: Zobrazení vlákna

Nyní, když máme inicializovaného uživatele, můžeme na stránce zobrazit konkrétní komunikační vlákno. Tento kód se vkládá za základní snippet. Prvním parametrem je DOM element, do kterého se má vlákno vykreslit.

Minimální použití

V nejjednodušším případě stačí zadat pouze unikátní kód vlákna. Název a URL se automaticky načtou z titulku a URL aktuální stránky.

<script>
  stromCom.thread(document.querySelector("#thread"), {
    /**
     * Unique thread code. Cannot be changed later. Max length 100. Allowed characters: [a-zA-Z0-9-_] (required)
     */
    "code": "order-12345"
  });
</script>

Základní použití

Doporučujeme vždy specifikovat alespoň název vlákna pro lepší přehlednost.

<script>
  stromCom.thread(document.querySelector("#thread"), {
    /**
     * Unique thread code. Cannot be changed later. Max length 100. Allowed characters: [a-zA-Z0-9-_] (required)
     */
    "code": "order-12345",

    /**
     * Thread display name (optional)
     */
    "name": "Objednávka 12345"
  });
</script>

Pokročilé se všemi vlastnostmi

Pro plnou kontrolu můžete definovat všechny dostupné parametry, včetně URL pro zpětný odkaz z notifikací a možnosti zakázat označování uživatelů.

<script>
  stromCom.thread(document.querySelector("#thread"), {
    /**
     * Unique thread code. Cannot be changed later. Max length 100. Allowed characters: [a-zA-Z0-9-_] (required)
     */
    "code": "order-12345",

    /**
     * Thread display name (optional)
     */
    "name": "Objednávka 12345",

    /**
     * URL of the page where the thread is embedded. A link will appear in the thread header. (optional)
     */
    "url": "https://www.example.com/order/?id=12345",

    /**
     * Enable or disable @mention suggestions for users (optional)
     */
    "userHint": false
  });
</script>

Krok 4: Notifikace a konfigurace

Snippet nabízí široké možnosti konfigurace pro přizpůsobení chování notifikací a pro pokročilou interakci pomocí API.

<script>
  stromCom.conf(   {
      /**
       * @param {Object} api
       */
      onLoad : function(api) {
        api.on(api.EVENT.APP_ADD, function(app) {
          // Control the embedded app via the API
        });
      },

    /**
     * Custom function for rendering notifications (optional)
     * @param {Function|null}
     */
    "notificationRenderer": null,

    /**
     * Callback fired when a new message count changes (optional)
     * @param {Function|null}
     */
    "onNotification": null,

    /**
     * CSS file URL injected into the snippet iframe when loading the app (optional)
     * Example: "https://www.example.com/custom.css"
     */
    "pageCSSPath": null,

    /**
     * Target element for the notification icon (optional)
     * @param {Function|Promise|HTMLElement}
     */
    "notificationElementTargetElement": null,

    /**
     * Always show the notification icon even when there are no new notifications (optional)
     * @param {boolean}
     */
    "notificationElementShowAlways": true,

    /**
     * Notification icon position for the default renderer: 1=top-left, 2=top-right, 3=bottom-right, 4=bottom-left (optional)
     * @param {Number|null}
     */
    "notificationElementPosition": 2,

    /**
     * Custom inline styles for the default notification button (optional)
     * @param {Object|null}
     */
    "notificationElementStyles": {"zIndex":1000},

    /**
     * CSS file URL used by the default notification renderer (optional)
     * Example: "https://www.example.com/notification.css"
     */
    "notificationElementCSSPath": null,

    /**
     * Callback invoked before the notification center opens (on notification icon click) (optional)
     * @param {Function|null}
     */
    "homeBeforeRender": null,

    /**
     * Callback invoked before the notification element is rendered (optional)
     * @param {Function|null}
     */
    "notificationElementBeforeRender": null,

    /**
     * Callback invoked after the notification element is rendered (optional)
     * @param {Function|null}
     */
    "notificationElementAfterRender": null,

    /**
     * Theme name applied to the host page via data-theme on <html>. Available: stromcom-default, stromcom-dark (optional)
     * Example: "stromcom-dark"
     */
    "theme": null
  });
</script>