JS SDK

As part of the Hint Marketplace we provide a JS SDK that must be used when creating apps designed to be embedded into the Hint UI.

The SDK

The SDK for sandbox can be found here and the production one here.

You need to include in your app by adding the following script tag:

<script src="https://api.staging.hint.com/hint-sdk.js"></script>

After including the SDK and your app is ready to be rendered you need to invoke the init function of the SDK.

HintSDK.init();

Available functions

HintSDK.init(callback) => null Indicates to Hint that the app is ready to render.

HintSDK.user => { id, name, email, first_name, last_name, partner_roles } Returns the user.

HintSDK.currentPatient => { id, name } | null Returns the currently selected patient or null if not patient is selected.

HintSDK.onCurrentPatientChanged(callback)Register a callback that will be called whenever the current patient is changed.

HintSDK.interaction => { id } | null Returns the interaction attached to the iframe session or null if there is no interaction.

HintSDK.close() => null Indicates to Hint to close the app container.

HintSDK.onClose(callback) Registers a callback that will be called when the app container is closed from Hint, usually by the user.

HintSDK.queryParams => [Object] | null Returns the Hint query params. Useful to build deep links that can be shared between users.

HintSDK.updateQueryParams([Object]) => null Updates the Hint query params. Useful to build deep links that can be shared between users.

HintSDK.onQueryParamsChanged(callback) Registers a callback that will be called when the Hint query params are updated.

HintSDK.fragment => String | null Returns the Hint query fragment. Useful to build deep links that can be shared between users.

HintSDK.updateFragment(String) => null Updates the Hint query fragment. Useful to build deep links that can be shared between users.

HintSDK.onFragmentChanged(callback) Registers a callback that will be called when the Hint query params are updated.

Deep Linking

Deep links allow your embedded app to maintain navigation state and create shareable URLs that restore specific views or data when opened. The SDK provides query parameters and URL fragments to support this functionality.

Query Parameters

Query parameters are key-value pairs that appear in the URL (e.g., ?view=details&id=123). Use them to store navigation state, filter selections, or other application state that should be shareable.

Reading query parameters:

// Get all query params as an object
const params = HintSDK.queryParams;
// Example: { view: 'details', id: '123' }

// Access specific values
if (params && params.view === 'details') {
  // Show details view
}

Updating query parameters:

// Update query params (merges with existing params)
HintSDK.updateQueryParams({ view: 'details', id: '123' });

// Clear a param by setting it to null
HintSDK.updateQueryParams({ view: null });

Listening for changes:

HintSDK.onQueryParamsChanged((params) => {
  // Handle navigation when params change
  if (params && params.view) {
    navigateToView(params.view);
  }
});

URL Fragments

Fragments are the part of the URL after the hash (e.g., #section-1). Use fragments for in-page navigation, scroll positions, or lightweight state that doesn't need to be in query params.

Reading fragments:

// Get the current fragment
const fragment = HintSDK.fragment;
// Example: 'section-1' or null if no fragment

Updating fragments:

// Update the fragment
HintSDK.updateFragment('section-1');

Listening for changes:

HintSDK.onFragmentChanged((fragment) => {
  // Handle fragment changes (e.g., scroll to section)
  if (fragment) {
    scrollToSection(fragment);
  }
});

Full Core Page Example

<script src="https://api.staging.hint.com/hint-sdk.js"></script>

<script>
  HintSDK.init();
</script>

<div class="w-full h-screen bg-gray-50 flex items-center justify-center p-4 min-h-64">
  <div class="text-center">
    <div class="w-16 h-16 bg-indigo-100 rounded-full flex items-center justify-center mx-auto mb-4">
      <svg class="w-8 h-8 text-indigo-600" fill="none" stroke="currentColor" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg">
        <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M10.325 4.317c.426-1.756 2.924-1.756 3.35 0a1.724 1.724 0 002.573 1.066c1.543-.94 3.31.826 2.37 2.37a1.724 1.724 0 001.065 2.572c1.756.426 1.756 2.924 0 3.35a1.724 1.724 0 00-1.066 2.573c.94 1.543-.826 3.31-2.37 2.37a1.724 1.724 0 00-2.572 1.065c-.426 1.756-2.924 1.756-3.35 0a1.724 1.724 0 00-2.573-1.066c-1.543.94-3.31-.826-2.37-2.37a1.724 1.724 0 00-1.065-2.572c-1.756-.426-1.756-2.924 0-3.35a1.724 1.724 0 001.066-2.573c-.94-1.543.826-3.31 2.37-2.37.996.608 2.296.07 2.572-1.065z"></path>
        <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M15 12a3 3 0 11-6 0 3 3 0 016 0z"></path>
      </svg>
    </div>
    <h1 class="text-xl font-semibold text-gray-900 mb-2">Integration Active</h1>
    <p class="text-gray-600 text-sm mb-6">Work in progress</p>

    <p class="text-xs text-gray-500">
      Powered by Partner App
    </p>
  </div>
</div>

Clinical Interaction Example

<script src="https://api.staging.hint.com/hint-sdk.js"></script>

<script>
  function updateHeading() {
    if (HintSDK.currentPatient && HintSDK.currentPatient.name) {
      const heading = document.getElementById('pet-membership-heading');
      if (heading) {
        heading.textContent = `Add pet to ${HintSDK.currentPatient.name}'s membership`;
      }
    }
  }

  HintSDK
    .init(data => {
      updateHeading();
    })
    .onCurrentPatientChanged(() => {
      updateHeading();
    })
    .onClose(() => console.log('Bye'));
</script>

<div class="w-full h-screen bg-gray-50 flex items-center justify-center p-4 min-h-64">
  <div class="max-w-2xl w-full bg-white rounded-lg shadow-md p-6">
    <div class="mb-6">
      <div class="flex items-center mb-4">
        <div class="w-12 h-12 bg-blue-100 rounded-full flex items-center justify-center mr-4">
          <svg class="w-6 h-6 text-blue-600" fill="none" stroke="currentColor" viewBox="0 0 24 24" xmlns="http://www.w3.org/2000/svg">
            <path stroke-linecap="round" stroke-linejoin="round" stroke-width="2" d="M12 6v6m0 0v6m0-6h6m-6 0H6"></path>
          </svg>
        </div>
        <div>
          <h1 id="pet-membership-heading" class="text-2xl font-semibold text-gray-900">Add Pet to Membership</h1>
          <p class="text-sm text-gray-500">Complete pet information for membership</p>
        </div>
      </div>
    </div>

    <div class="bg-gray-50 rounded-lg p-4 mb-6">
      <div class="space-y-3">
        <div>
          <span class="text-xs font-medium text-gray-500 uppercase">Pet Name</span>
          <p class="text-sm text-gray-900 mt-1">Fluffy</p>
        </div>
        <div>
          <span class="text-xs font-medium text-gray-500 uppercase">Species</span>
          <p class="text-sm text-gray-900 mt-1">Dog</p>
        </div>
        <div>
          <span class="text-xs font-medium text-gray-500 uppercase">Breed</span>
          <p class="text-sm text-gray-900 mt-1">Golden Retriever</p>
        </div>
        <div>
          <span class="text-xs font-medium text-gray-500 uppercase">Status</span>
          <p class="text-sm text-gray-900 mt-1">
            <span class="inline-flex items-center px-2.5 py-0.5 rounded-full text-xs font-medium bg-yellow-100 text-yellow-800">
              Pending Addition
            </span>
          </p>
        </div>
      </div>
    </div>

    <div class="flex justify-end">
      <button type="button" onclick="HintSDK.close()" class="cursor-pointer px-4 py-2 bg-gray-600 text-white rounded-md hover:bg-gray-700 transition-colors duration-200 font-medium text-sm">
        Cancel
      </button>
    </div>

    <div class="mt-4 pt-4 border-t border-gray-200">
      <p class="text-xs text-gray-500 text-center">
        Powered by Partner App
      </p>
    </div>
  </div>
</div>