Custom apps

A custom app is any software TellsU doesn’t have built-in capture for: a Shopify app, an Adobe Commerce extension, a VS Code extension, a desktop app, a website. You pass the details that matter, and TellsU attaches them to every submission.

Choose Custom app as the platform when you add the app in the TellsU dashboard. Its Installation tab has the snippets below with your public key filled in; the examples here use pk_yourpublickey in its place.

The widget works anywhere you can run JavaScript in a web page. Where it can’t, use a link.

Add the widget

npm

For apps with a build step.

1. Install the package:

   npm install @tellsu/widget

2. Add an element where the widget should appear, on whichever of your app’s pages should show it:

   <div id="feedback"></div>

3. Mount the widget in a script that page runs, with your app’s version. Add what it runs inside and on, its release channel and edition, or the screen, as they apply:

   import { TellsU } from '@tellsu/widget';
   
   TellsU.mount('#feedback', {
     appKey: 'pk_yourpublickey', // required; everything else is optional
     version: '2.4.1',
     env: {
       host: 'Adobe Commerce',
       host_version: '2.4.7',
       runtime: 'PHP',
       runtime_version: '8.3',
       channel: 'stable',
       edition: 'pro',
     },
     screen: 'settings',
   });

React

For pages built with React.

1. Install the package:

   npm install @tellsu/react

2. Add the component:

   import { TellsUWidget } from '@tellsu/react';
   
   export function Feedback() {
     return (
       <TellsUWidget
         appKey="pk_yourpublickey"
         version="2.4.1"
         env={{
           host: 'Adobe Commerce',
           host_version: '2.4.7',
           runtime: 'PHP',
           runtime_version: '8.3',
           channel: 'stable',
           edition: 'pro',
         }}
         screen="settings"
       />
     );
   }

3. Render <Feedback /> where the widget should appear.

The props are the widget’s options, plus className for the element it mounts into. It mounts once, even under StrictMode, and remounts only when an option’s value changes, so passing a new env object on each render is fine.

Without a build step

1. Download tellsu.min.js from the Installation tab and serve it with your app’s own files. The tab shows its version and a SHA-384 checksum to compare with shasum -a 384 tellsu.min.js.

2. In the page’s HTML, add an element for the widget, then the file:

   <div id="feedback"></div>
   <script src="tellsu.min.js"></script>

3. Mount the widget in a script the page runs after tellsu.min.js:

   TellsU.mount('#feedback', {
     appKey: 'pk_yourpublickey', // required; everything else is optional
     version: '2.4.1',
     env: {
       host: 'Adobe Commerce',
       host_version: '2.4.7',
       runtime: 'PHP',
       runtime_version: '8.3',
       channel: 'stable',
       edition: 'pro',
     },
     screen: 'settings',
   });

With a link

Where code can’t run or isn’t wanted, link to the hosted page. Only the public key is required:

https://go.tellsu.com/pk_yourpublickey

Add query parameters to send your app’s version and what it runs inside and on, its release channel and edition:

https://go.tellsu.com/pk_yourpublickey?v=2.4.1&h=Adobe%20Commerce&hv=2.4.7&rt=PHP&rv=8.3&ch=stable&ed=pro

Use it anywhere a link can go, including a button or widget of your own. Link parameters lists every value a link can carry.

What’s sent

Custom apps keep your app’s version and screen, the host and runtime with their versions, the release channel and the edition.

The hosted page detects the browser and operating system itself, from wherever it’s opened. A link opened outside your app (from a README, say) carries only what you put in it, and the browser is the one it was opened in.

The widget doesn’t find the screen by itself in a custom app, since a page address could carry anything. Pass screen with a short name for the part of your app it’s on, if that’s useful to you.