Skip to main content

Getting Started

This guide explains how to integrate the Paylisher Web SDK into your website or web application.

Key Features​

  • Event Capture: Track page views and custom events.
  • User Identification: Associate events with known users.
  • Auto-Capture: Automatically captures $pageview and deep link events.
  • Attribution: Supports deferred deep linking and web-to-app campaign attribution.
  • User Properties: Supports $set and $set_once updates with events.

Installation​

You can integrate the SDK in two ways.

Option 1: Script tag (vanilla websites)​

Add this once in your global layout (<head> or before </body>):

<script src="https://your.sdk.host/paylisher.min.js"></script>
<script>
  window.paylisher.init('YOUR_API_KEY', {
    dataStudioHost: 'https://your.paylisher.host',
    debug: false,
    deepLinkConfig: {
      captureDeepLinkEvents: true,
      autoHandleDeepLinks: true
    },
    deferredDeepLinkConfig: {
      enabled: false
    }
  });
</script>

Important: Add this snippet only once in your global template, not separately on every page. Note: campaignHost is optional and only needed for deferred deep link matching APIs.

Option 2: NPM package (React, Next.js, Vue, Nuxt, etc.)​

npm install paylisher-sdk

Initialize once in your app root:

import Paylisher from 'paylisher-sdk';

Paylisher.init('YOUR_API_KEY', {
  dataStudioHost: 'https://your.paylisher.host',
  debug: false,
  deepLinkConfig: {
    captureDeepLinkEvents: true,
    autoHandleDeepLinks: true,
  },
  deferredDeepLinkConfig: {
    enabled: false,
  },
});

Optional advanced config:

Paylisher.init('YOUR_API_KEY', {
  dataStudioHost: 'https://your.paylisher.host',
  campaignHost: 'https://your.campaign.host',
  campaignResolveHost: 'https://your.resolve.host',
});

Configuration notes:

  • campaignHost: Used for deferred deep link click/match APIs (/deferred-deeplink/click and /deferred-deeplink checks).
  • campaignResolveHost: Used to resolve campaign metadata for deep links (/campaign/resolve/{keyName}).
  • Analytics-only setup: both can be omitted.
  • If you use deferred deep links: set campaignHost.
  • If you need campaign resolve/metadata enrichment for deep links: set campaignResolveHost (or rely on SDK default resolve host).

Alternative snippet rollout (global array loader)​

Another product owner can roll this out with the following flow:

  1. Provide 2 values to the developer:
  • project token (for example: phc_xxx)
  • api_host (for example: https://ds-tr.paylisher.com)
  1. Add the snippet to exactly one global layout file (index.html, app layout, master template). Do not add per-page.
<script>
!function(t,e){
  var o,n,p,r;
  e.__SV||(window.paylisher=e,e._i=[],e.init=function(i,s,a){
    function g(t,e){
      var o=e.split(".");
      2==o.length&&(t=t[o[0]],e=o[1]),
      t[e]=function(){ t.push([e].concat(Array.prototype.slice.call(arguments,0))) }
    }
    (p=t.createElement("script")).type="text/javascript",
    p.crossOrigin="anonymous",
    p.async=!0,
    p.src=(s.api_host||"").replace(/\/$/,"")+"/static/array.js",
    (r=t.getElementsByTagName("script")[0]).parentNode.insertBefore(p,r);

    var u=e;
    void 0!==a?u=e[a]=[]:a="paylisher",
    u.people=u.people||[],
    u.toString=function(t){ var e="paylisher"; return"paylisher"!==a&&(e+="."+a),t||(e+=" (stub)"),e },
    u.people.toString=function(){ return u.toString(1)+".people (stub)" };

    o="init capture identify alias set_config reset debug get_distinct_id get_session_id get_session_replay_url group resetGroups getGroups reloadFeatureFlags getFeatureFlag getFeatureFlagPayload isFeatureEnabled onFeatureFlags startSessionRecording stopSessionRecording sessionRecordingStarted captureException".split(" ");
    for(n=0;n<o.length;n++) g(u,o[n]);

    e._i.push([i,s,a])
  },e.__SV=1)
}(document,window.paylisher||[]);

paylisher.init("phc_YOUR_TOKEN", {
  api_host: "https://ds-tr.paylisher.com",
  person_profiles: "identified_only"
});
paylisher.capture("$pageview");
</script>
  1. If the app is SPA, send pageview on route changes too:
paylisher.capture("$pageview", { path: location.pathname, url: location.href });
  1. Verification checklist:
  • .../static/array.js should load in browser network tab.
  • Event requests should be visible (/e or /batch).
  • Manual check: paylisher.capture("manual_test_event")

If needed, this can also be prepared as short integration variants for Vanilla HTML, React/Next, and GTM.

Capturing events​

You can send custom events with track:

Paylisher.track('user_signed_up');

Setting event properties​

Paylisher.track('purchase_completed', {
  amount: 99.99,
  currency: 'USD',
  product_id: 'sku_123',
});

Setting user properties ($set) and first-time properties ($set_once)​

Paylisher.track(
  'user_signed_up',
  { plan: 'pro' },
  {
    email: '[email protected]',
    name: 'Jane Doe',
  },
  {
    signup_date: '2026-02-25',
  }
);

Identifying users​

Associate future events with your internal user id:

Paylisher.identify('user_12345');

Call identify right after login (and on app load if a user session already exists). For detailed guidance, see Identify User.

campaignHost (or deferredDeepLinkAPIHost) is required only if you use deferred deep link click/match APIs.

When user clicks an install/open button on web, record deferred deep link intent:

await Paylisher.deferredDeepLink(
  'https://app.example.com/promo/summer',
  'summer-campaign-2026'
);

Then, on app side, fetch deferred deep link match:

const result = await Paylisher.fetchDeferredDeeplink();

if (result?.matched) {
  console.log('Matched deeplink:', result.deeplink_url);
}

Callback API:

await Paylisher.checkDeferredDeepLink({
  onSuccess: (match) => {
    console.log('Deferred match:', match.url);
  },
  onNoMatch: () => {
    console.log('No deferred match');
  },
  onError: (error) => {
    console.error('Deferred deep link error:', error.message);
  },
});

Notes​

  • SDK automatically tracks $pageview after initialization.
  • URL parameters (UTM, fbclid, gclid, ttclid, and custom params) are attached to events and attribution payloads.
  • Enable debug: true during development to inspect SDK logs.
  • If your API is exposed under a path (for example /backend via ingress rewrite), include that path in dataStudioHost.
  • For deep link manager methods, see Deep Link Integration.