JavaScript SDK を使用して Notiondesk Messenger を制御する

Messenger JavaScript SDK を使用すると、Messenger をアプリケーションのインターフェースと状態に直接統合できます。

あなたはできる：

• 自分のUIからメッセンジャーを開閉する

• 訪問者をヘルプ、メッセージ、お問い合わせ、または変更履歴に直接誘導する

• 独自のメッセンジャーランチャーを作成

• Messengerイベントに反応する

• Messengerをアプリケーションのテーマと言語に同期させる

• ページを再読み込みせずに認証済みユーザーを更新する

• 実行時に位置とスタッキングを変更する

• MessengerをReactおよびVueアプリケーションの状態と統合する

• 必要に応じてメッセンジャーを削除して再初期化してください。

標準のMessengerインストールコードでは制御できない、より詳細な制御が必要なアプリケーションには、SDKを使用してください。

SDKをインストールしてください

公式パッケージをインストールしてください。

Yarnも使用できます。

またはpnpm:

Messengerを初期化する

initNotiondesk() をインポートし、メッセンジャーIDを入力してください。

initNotiondesk() は Messenger が使用可能になった時点で解決されるため、SDK メソッドを呼び出す前に初期化が完了するまで待つのが最も安全な方法です。

Notiondesk Messengerはブラウザで初期化する必要があります。サーバーサイドレンダリング中に初期化しないでください。

ReactとNext.jsのインストールについては、 「ReactとNext.jsを使用してNotiondesk Messengerをインストールする方法」を参照してください。

Messengerを開く、閉じる、切り替える

オープンメッセンジャー

show() を使用してください。

例えば：

クローズメッセンジャー

hide() を使用してください:

メッセンジャーを切り替える

Messengerが閉じているときに開き、開いているときに閉じるには、toggle() を使用してください。

toggle() は、アプリケーションが独自のメッセンジャーボタンを提供する場合に特に役立ちます。

特定のメッセンジャーセクションを開く

showTab() を使用して、特定のモジュールで Messenger を直接開きます。

利用可能なタブは以下のとおりです。

npm install @notiondesk-so/messenger-js-sdk

yarn add @notiondesk-so/messenger-js-sdk

pnpm add @notiondesk-so/messenger-js-sdk

import { initNotiondesk } from "@notiondesk-so/messenger-js-sdk";

const notiondesk = await initNotiondesk({
  messengerId: "YOUR_MESSENGER_ID",
});

const notiondesk = await initNotiondesk({
  messengerId: "YOUR_MESSENGER_ID",
});

await notiondesk.show();

await notiondesk.show();

document.querySelector("#support")?.addEventListener("click", () => {
  void notiondesk.show();
});

await notiondesk.hide();

await notiondesk.toggle();

notiondesk.showTab("help");

例えば：

showTab() は、Messenger が閉じている場合にも開きます。

要求されたモジュールは、Messengerの設定で有効になっている必要があります。たとえば、変更ログモジュールが無効になっている場合、showTab("changelog")は変更ログに切り替わりません。

これにより、アプリケーションのインターフェースのさまざまな部分を、異なるサポート体験に接続することが可能になります。

例えば：

helpButton.addEventListener("click", () => {
  notiondesk.showTab("help");
});

updatesButton.addEventListener("click", () => {
  notiondesk.showTab("changelog");
});

contactButton.addEventListener("click", () => {
  notiondesk.showTab("contact");
});

• ヘルプセンター→ showTab("help")

• AIに質問する→ showTab("messages")

• サポートに問い合わせる→ showTab("contact")

• 新着情報→ showTab("changelog")

独自のメッセンジャーボタンを使用する

デフォルトのNotiondeskランチャーを使用する必要はありません。

Messengerの設定で「ランチャーを表示」をオフにしてから、SDKを使用して独自のインターフェースからMessengerを開いてください。

例えば：

これは、サポート機能を既存のナビゲーションバー、アカウントメニュー、ダッシュボード、フローティングボタン、またはアプリケーションシェルに統合する必要がある場合に役立ちます。

カスタムランチャーを使用する場合、同じコントロールでメッセンジャーを開閉する必要がある場合は、toggle() を優先してください。

Messengerイベントを聞く

SDKは、on()およびoff()を通じてイベントを公開します。

例えば：

on() は購読解除関数を返します。

利用可能なメッセンジャーイベント

const notiondesk = await initNotiondesk({
  messengerId: "YOUR_MESSENGER_ID",
});

document.querySelector("#help")?.addEventListener("click", () => {
  void notiondesk.toggle();
});

notiondesk.on("messenger:show", () => {
  console.log("Messenger opened");
});

notiondesk.on("messenger:hide", () => {
  console.log("Messenger closed");
});

const unsubscribe = notiondesk.on("messenger:show", () => {
  console.log("Messenger opened");
});

// Later
unsubscribe();

メッセンジャーセクションの訪問者がどの機能を使用しているかを追跡します

messenger:tabChanged イベントには、現在および前のタブが含まれます。

例えば、Messengerのアクティビティを分析プラットフォームに転送することができます。

自分のランチャーを同期させておきましょう

イベントを使用すると、UIをMessengerの状態と同期させることもできます。

Messengerのテーマを変更する

Messengerをリロードせずにライトモードとダークモードを切り替えるには、setTheme()を使用してください。

または：

例えば、Messengerをアプリケーションのテーマと同期させるには、次のようにします。

オペレーティングシステムのテーマ変更にも反応できます。

Messengerの色、フォント、ランチャーの外観、その他のブランド設定については、Notiondesk ダッシュボードを使用してください。SDK のテーマコントロールは、アクティブなカラースキームを切り替えるためのものです。

Messengerの言語を変更する

setLanguage() を使用してください:

これは、アプリケーションに既に独自の言語セレクターが備わっている場合に便利です。

Notiondesk で、Messenger に対して要求されたロケールが有効になっている必要があります。

ロケールが有効になっていない場合、Messengerは代わりに設定済みの言語を保持します。

初期化後にメッセンジャーを更新する

Messengerが既にロードされた後にアプリケーションの状態が変更された場合は、updateConfig()を使用してください。

notiondesk.on(
  "messenger:tabChanged",
  ({ tabName, previousTab }) => {
    console.log("Messenger tab:", tabName);
  },
);

notiondesk.on("messenger:show", () => {
  analytics.track("support_opened");
});

notiondesk.on("messenger:tabChanged", ({ tabName }) => {
  analytics.track("support_tab_opened", {
    tab: tabName,
  });
});

notiondesk.on("messenger:show", () => {
  helpButton.setAttribute("aria-expanded", "true");
});

notiondesk.on("messenger:hide", () => {
  helpButton.setAttribute("aria-expanded", "false");
});

notiondesk.setTheme("dark");

notiondesk.setTheme("light");

notiondesk.setTheme(
  isDarkMode ? "dark" : "light",
);

const colorScheme = window.matchMedia(
  "(prefers-color-scheme: dark)",
);

function syncMessengerTheme() {
  notiondesk.setTheme(
    colorScheme.matches ? "dark" : "light",
  );
}

syncMessengerTheme();

colorScheme.addEventListener(
  "change",
  syncMessengerTheme,
);

notiondesk.setLanguage("fr");

notiondesk.setLanguage(currentLocale);

認証済みユーザーを更新する

ユーザーがサインインした後：

Messengerは、ページの再読み込みを必要とせずに、現在のユーザー情報を更新します。

匿名ユーザーに戻る

ユーザーがログアウトしたとき：

認証フロー全体については、 「Notiondesk Messenger でログインしているユーザーを識別する」を参照してください。

メッセンジャーの位置を変更する

Messengerは実行時に移動できます。

対象となる職種は以下のとおりです。

notiondesk.updateConfig({
  userToken,
});

notiondesk.updateConfig({
  userToken: null,
});

notiondesk.updateConfig({
  position: "bottom-left",
});

• bottom-right

• bottom-left

デフォルトのランチャー位置は通常、Notiondesk ダッシュボードで設定します。アプリケーションで一時的なランタイムオーバーライドが必要な場合は、updateConfig() を使用してください。

例えば、別のフローティング要素が同じ角を占めている場合、Messengerを移動させることができます。

積み重ねレベルを変更する

Messengerを他のアプリケーション要素の上に表示する必要がある場合：

認証済みユーザーでメッセンジャーを使用する

Messengerを初期化する際に、署名付きユーザートークンを渡してください。

匿名で開始し、後でユーザーを特定することもできます。

トークンはバックエンドで生成する必要があります。

ブラウザのコードに Notiondesk アプリの秘密情報を決して公開しないでください。

認証とログアウトの完全な流れについては、 「Notiondesk Messenger でログインしているユーザーを識別する」を参照してください。

メッセンジャーを削除

現在のメッセンジャーインスタンスを完全に削除するには、destroy() を使用してください。

destroy() は、以下の場合に使用します。

notiondesk.updateConfig({
  zIndex: 10000,
});

const notiondesk = await initNotiondesk({
  messengerId: "YOUR_MESSENGER_ID",
  userToken,
});

const notiondesk = await initNotiondesk({
  messengerId: "YOUR_MESSENGER_ID",
});

notiondesk.updateConfig({
  userToken,
});

notiondesk.destroy();

• 現在のページにはメッセンジャーは存在すべきではありません

• ユーザーアカウントが切り替えられています

• アプリケーションがメッセンジャー統合をアンマウントしています

• 新しいメッセンジャーセッションを初期化する必要があります

Messengerを破棄した後でも、再度初期化することができます。

Messengerを初期化せずにロードする

初期化をより細かく制御する必要があるアプリケーションの場合は、loadNotiondesk() を使用してください。

ほとんどのアプリケーションでは、代わりにinitNotiondesk()を使用する必要があります。

loadNotiondesk() は、Messenger SDK のロードと Messenger 自体の起動がアプリケーションのライフサイクルの異なる時点で行われる必要がある場合に役立ちます。

既に読み込まれているメッセンジャーAPIにアクセスします

Messengerが既にロードされている場合、getNotiondesk()を使用してAPIに同期的にアクセスします。

Messengerがまだロードされていない場合、getNotiondesk()はnullを返します。

通常のアプリケーション初期化には、initNotiondesk() を推奨します。

Reactのコントロールと状態

Reactアプリケーションでは以下を使用する必要があります。

useNotiondesk() は、メッセンジャーのコントロールと現在の読み込み状態の両方を提供します。

例えば：

利用可能な値は次のとおりです。

import {
  loadNotiondesk,
} from "@notiondesk-so/messenger-js-sdk";

const notiondesk = await loadNotiondesk();

await notiondesk.init({
  messengerId: "YOUR_MESSENGER_ID",
});

import {
  getNotiondesk,
} from "@notiondesk-so/messenger-js-sdk";

getNotiondesk()?.show();

import {
  NotiondeskProvider,
  useNotiondesk,
} from "@notiondesk-so/messenger-js-sdk/react";

function SupportButton() {
  const {
    show,
    status,
  } = useNotiondesk();

  return (
    <button
      disabled={status !== "ready"}
      onClick={() => void show()}
    >
      Contact support
    </button>
  );
}

イベント購読などのAPIが必要な場合は、apiを使用してください。

テーマやロケールなどの設定プロパティは、可能な限りNotiondeskProviderで安定させるようにしてください。

実行時の変更については、プロバイダ構成を繰り返し変更するよりも、setTheme()、setLanguage()、またはupdateConfig()を使用することをお勧めします。

Vueのコントロールと状態

Vueアプリケーションは、以下の方法でMessengerにアクセスできます。

例えば：

Vueとの統合により、Messenger API、ステータス、エラー、およびコアSDKと同じランタイムコントロールも利用可能になります。

一般的なSDKレシピ

カスタムヘルプボタンを作成する

Messengerの設定でデフォルトのランチャーをオフにしてください。

ヘルプセンターを直接開いてください

AIアシスタントを直接開く

Messengerでは、メッセージモジュールを有効にして設定する必要があります。

お問い合わせフォームを直接開く

「新機能」リンクから変更履歴を開いてください。

特定のアプリケーションルートでメッセンジャーを非表示にする

メッセンジャーを他の浮遊要素から離す

Messengerの使用状況を追跡する

ログイン後にメッセンジャーを更新してください

ログアウト後にユーザーをクリアする

トラブルシューティング

import { useEffect } from "react";
import { useNotiondesk } from "@notiondesk-so/messenger-js-sdk/react";

function MessengerAnalytics() {
  const { api } = useNotiondesk();

  useEffect(() => {
    if (!api) {
      return;
    }

    return api.on("messenger:show", () => {
      analytics.track("support_opened");
    });
  }, [api]);

  return null;
}

import {
  useNotiondesk,
} from "@notiondesk-so/messenger-js-sdk/vue";

<script setup lang="ts">
import {
  useNotiondesk,
} from "@notiondesk-so/messenger-js-sdk/vue";

const {
  show,
  showTab,
  isReady,
} = useNotiondesk();
</script>

<template>
  <button
    :disabled="!isReady"
    @click="show()"
  >
    Contact support
  </button>

  <button @click="showTab('changelog')">
    What's new
  </button>
</template>

helpButton.addEventListener("click", () => {
  void notiondesk.toggle();
});

notiondesk.showTab("help");

notiondesk.showTab("messages");

notiondesk.showTab("contact");

notiondesk.showTab("changelog");

if (window.location.pathname.startsWith("/checkout")) {
  await notiondesk.hide();
}

notiondesk.updateConfig({
  position: "bottom-left",
});

notiondesk.on("messenger:show", () => {
  analytics.track("support_opened");
});

notiondesk.on("messenger:tabChanged", ({ tabName }) => {
  analytics.track("support_section_opened", {
    section: tabName,
  });
});

notiondesk.updateConfig({
  userToken,
});

notiondesk.updateConfig({
  userToken: null,
});

try {
  const notiondesk = await initNotiondesk({
    messengerId: "YOUR_MESSENGER_ID",
  });
} catch (error) {
  console.error(
    "Could not initialize Notiondesk Messenger",
    error,
  );
}

notiondesk.updateConfig({
  zIndex: 10000,
});

notiondesk.updateConfig({
  userToken: null,
});

notiondesk.destroy();

const { show, status } = useNotiondesk();

return (
  <button
    disabled={status !== "ready"}
    onClick={() => void show()}
  >
    Contact support
  </button>
);