Setup & Integration

Choose your HEA, create a stable install_id, grab the embed snippet, and share whitelisting instructions when needed.
🧩 Install on your site
1. Select the HEA you want to install
We’ll customize the snippet and links with the correct creator_id and hea_id. If an install_id exists, we’ll use it by default (recommended).
Pick a HEA to see a generic embed snippet and integration links.
creator_id: (pending)
hea_id: (none selected)
install_id: (none)
Start with the Ask bar, then add the pop-up if you want a global helper. 

            

              Paste this near the end of your site’s <body>.
              
            

            

              We pre-fill the creator_id and hea_id.
              If an install_id exists, we’ll use it by default (recommended for domain whitelisting & transfers).
            

          

        

      


      
      

        

          

            
2. Install ID (recommended)

            

              Create a stable install_id for your website integration. It enables domain allowlisting and safer HEA transfers.
            

          

          

            
            
          

        


        

          

            

              Why use install_id?

              • You can allowlist domains (allowed_domains) so only authorized sites can run the widget.

              • Transfers are safer: your customer’s embed stays stable even if ownership changes.

              • You can have multiple installs per HEA (e.g., staging + production domains).
            


            

              
              
              
Select a HEA to load installs.

            


            

              
              

                install_id:
                (none)
                
              

              

            

          


          

            
            
            

              If empty → all domains are allowed (not recommended for public production). Subdomains are allowed when you add the apex (e.g. domain.com allows www.domain.com).
            


            

              
              
              
              
            


            


            

              
              

                Tip: Prefer Disable instead of deleting. ⚠️ Deleting an install_id can break a customer deployment with no rollback.
              

            

          

        


        

          
          
This list is read from KV via /api/hea/installs?action=list_installs&expand=1.

          

            
              

                install_id
                status
                domains
                updated
              

            
            
              
Select a HEA to load installs.

            
          

        

      


      
      

        

          

            
3. Consent / Cookies (CMP)

            

              Optional but recommended. Add this above the HEA widget snippet so consent is available early.
            

          

        


        

          

            
            

            

              
              
              

                Cookiebot is ready. Generic is a template for other CMPs.
              

            

          


          

            
            

            

              Paste this near the top of <body> (before HEA).
              
            

            

          

        

      


      
      

        

          

            
4. Explore integration patterns & test pages

            

              Visual overview and live test pages for the main integration styles:
              magic ask bar, conversation block, and floating pop-up.
            

          

        


        

          

            
            

              SVG overview for web and mobile. Use it in client decks to explain where HEA appears.
            

            
              🧩
              Open integration patterns
            
          


          

            
            

              Live demo pages for ask bar, floating pop-up, and block embed.
              We’ll propagate your creator_id and
              hea_id via query params (and keep install_id for embed).
            

            

              
                🔎
                Ask bar test
              
              
                💬
                Floating pop-up test
              
              
                📦
                Conversation block test
              
            

          

        

      


      
      

        

          

            
5. Whitelisting (if your WAF blocks the crawler)

            

              Only needed when your site uses an aggressive Web Application Firewall or bot protection.
            

          

        


        

          Most sites work out of the box. If your job log mentions 403 / bot detection / WAF,
          send this guide to your webmaster or hosting provider.
        


        
          🛡️
          Open whitelisting guide
        

        

          The guide includes a ready-to-forward email with
          sales@hea-world.com in copy and the
          HEA-Crawler/1.0 user-agent to allow.
        

      

    

  


  
  

  

  `
          ].join('\n');
        }

        case 'popup': {
          const pos = window.HEA_SETUP_DEFAULT_POSITION || '';
          
          const ox  = Number.isFinite(Number(window.HEA_SETUP_DEFAULT_OFFSET_X))
            ? Number(window.HEA_SETUP_DEFAULT_OFFSET_X)
            : null;
          const oy  = Number.isFinite(Number(window.HEA_SETUP_DEFAULT_OFFSET_Y))
            ? Number(window.HEA_SETUP_DEFAULT_OFFSET_Y)
            : null;

          const lines = [
            '',
            '<\\/script>');
          return lines.join('\n');
        }

        case 'block': {
          const qs = new URLSearchParams();

          // prefer install_id (recommended)
          if (safeInstall) {
            qs.set('install_id', safeInstall);
          } else {
            qs.set('creator_id', safeCreator);
            qs.set('hea_id', safeHea);
          }

          // embed flags (good defaults)
          qs.set('embed', '1');
          qs.set('chromeless', '1');

          return [
            '',
            ''
          ].join('\n');
        }
      }
    }

    // -----------------------------
    // CMP snippet builder (unchanged)
    // -----------------------------
    function buildCmpSnippet({ mode = 'auto', vendor = 'cookiebot' } = {}) {
      const base = `${getPublicBase()}/public/CMP_connectors`;
      const close = '<\\/script>';

      if (mode === 'deny_all') {
        return [
          '',
          `