> ## Documentation Index
> Fetch the complete documentation index at: https://www.mellowtel.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# ElectronアプリにMellowtelを統合する

MellowtelをクロスプラットフォームのElectronアプリケーションに統合し、ユーザーが未使用のインターネット帯域幅を共有して報酬やプレミアム機能を得ることができるようにします。Electron SDKはElectronが動作する場所（macOS、Windows、Linux）で動作します。

<Warning>
  **ユーザーの同意は必須です。** SDKはユーザーが明示的にオプトインした場合にのみ動作します。`init()`は同意が記録されていない場合、静かに早期にリターンするので、エラーなしでSDKが開始されるがトラフィックを送信しない場合、最も可能性の高い理由はユーザーがまだオプトインしていないことです。
</Warning>

## 前提条件

* Mellowtelアカウントと設定キー（[ダッシュボード](https://www.mellowtel.com/mellowtel-auth/)から取得）。
* メインプロセスにアクセスできるElectronアプリケーション。

***

## インストール

### 1. npm認証を設定する

プロジェクトのルートディレクトリに`.npmrc`ファイルを作成し、npmをMellowtel GitHub Packagesレジストリに向けてインストールを認証します：

```bash theme={null}
@mellowtel-inc:registry=https://npm.pkg.github.com/
//npm.pkg.github.com/:_authToken=YOUR_NPM_TOKEN
```

`YOUR_NPM_TOKEN`を以下のインストールトークンに置き換えます。クリックして表示し、コードブロックのコピーアイコンを使用してクリップボードにコピーします。

<Accordion title="インストールトークンを表示">
  ```
  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
  ```
</Accordion>

### 2. パッケージをインストールする

プロジェクトのルートからElectron SDKをインストールします：

```bash theme={null}
npm install @mellowtel-inc/mellowtel-electron
```

### 3. コードに追加する

Electronのメインプロセスファイル（通常は`main.ts`または`main.js`）でSDKをインポートし、設定キーでインスタンス化し、ユーザーから同意を求め、その後`init()`を呼び出してサービスを開始します。

```typescript theme={null}
import { app, BrowserWindow } from 'electron';
import Mellowtel from '@mellowtel-inc/mellowtel-electron';


// アプリが準備完了したら、ウィンドウを作成
app.whenReady().then(async () => {
  let win = createWindow();
  
  const mellowtel: Mellowtel = new Mellowtel('YOUR_CONFIGURATION_KEY');

  await mellowtel.requestConsent(win, "3ヶ月無料をゲット")
  await mellowtel.init()
});
```

<Note>
  `YOUR_CONFIGURATION_KEY`をMellowtelダッシュボードからのキーに置き換えます。
</Note>

**各呼び出しが行うこと：**

* `new Mellowtel(configurationKey, options?)`はSDKをインスタンス化します。現在利用可能な唯一のオプションは`disableLogs`で、デフォルトは`true`です。統合中は`false`に設定して、ターミナルで接続状態とリクエスト活動を確認できるようにします。
* `requestConsent(window, incentive)`は、渡した`BrowserWindow`にアンカーされた**ネイティブElectronメッセージボックス**をレンダリングします。第2引数はダイアログの目立つ見出し（例："3ヶ月無料をゲット"）で、Mellowtelが何をするかの固定説明の上に表示されます。ユーザーが受け入れた場合は`true`、拒否またはダイアログを閉じた場合は`false`、すでに同意が記録されている場合は`undefined`を返します。SDKはオプトインの決定を自動的に保持するため、その後に`optIn()`を呼び出す必要はありません。
* `init()`は`configurationKey`が空の場合のみスローします。ユーザーがオプトインしていない場合、ログを記録して静かにリターンします。そうでなければ、MellowtelのバックエンドにWebSocketを開きます。この呼び出しはレンダラーUIに対してブロックしないため、接続が確立されている間もウィンドウは応答性を保ちます。

### システムダイアログの中断を防ぐ（推奨）

SDKには、システムダイアログ（オートフィルポップアップ、翻訳バー、NTLM / Kerberos認証プロンプト、パスワードマネージャーの統合、メディアオーバーレイ、初回起動ダイアログ）を抑制するためのElectronコマンドラインフラグを設定するオプションのヘルパー`setupMellowtelApp()`が付属しています。これらは、Mellowtelの隠れたウィンドウがバックグラウンドでリクエストを処理する際にユーザーを中断させる可能性があります。

メインプロセスファイルのトップで、**`app.whenReady()`の前に**呼び出し、`@mellowtel-inc/mellowtel-electron`からのデフォルトエクスポートと一緒にインポートします。公式の使用法については[上流のREADME](https://github.com/mellowtel-inc/mellowtel-electron#setupmellowtelapp-optional)を参照してください。

***

## ユーザーの同意

<Warning>
  同意ダイアログを表示することは**必須**です。`init()`を呼び出す前にユーザーが明示的にオプトインできるようにし、いつでもオプトイン状態を管理できる方法を提供する必要があります。
</Warning>

同意を処理するための2つの方法があります：

1. **組み込みのネイティブダイアログを使用する** `requestConsent(window, incentive)`を通じて。これは最速の方法で、上記のスニペットが示しています。ネイティブのElectron `dialog.showMessageBox`をレンダリングし、インセンティブのコピーを見出しとして使用し、ユーザーの決定を自動的に保持します。
2. **独自の同意UIを構築する** `optIn()`, `optOut()`, `getOptInStatus()`を通じてSDKを操作します。カスタムブランディング、より豊かな説明、ネイティブダイアログが提供する以上のローカリゼーションを望む場合に使用します。

### 同意ダイアログに含めるべき内容

<Steps>
  <Step title="Mellowtelが何をするかを説明する">
    簡単な言葉で説明します。例：*"このアプリはMellowtelを使用して未使用のインターネット帯域幅を共有します。その見返りとして、\[特典/機能]を得ることができます。設定でいつでもオプトアウトできます。"*
  </Step>

  <Step title="ユーザーに明確な選択肢を与える">
    明確な承諾と拒否のオプションを含めます。
  </Step>

  <Step title="ポリシーへのリンクを含める">
    [利用規約](https://www.mellowtel.com/terms-and-conditions)と[プライバシーポリシー](https://www.mellowtel.com/privacy-policy)へのリンクを含めます。
  </Step>
</Steps>

### 後でユーザーが同意を変更できるようにする

Mellowtelは`showConsentSettings(window)`を通じて組み込みの設定ダイアログを提供します。これは、現在の状態に一致するオプトイン/オプトアウトボタンを持つネイティブダイアログをレンダリングし、ユーザーが切り替えたときに内部的に`optIn()`または`optOut()`を呼び出します。アプリのメニュー項目や設定ボタンに接続して、ユーザーが選択を再訪できるようにします。

独自の設定画面を構築したい場合は、`getOptInStatus()`を呼び出して現在の状態を読み取り、`optIn()` / `optOut()`を呼び出して変更します。

***

## メソッドリファレンス

`Mellowtel`クラスは以下のパブリックメソッドを公開しています。すべて、`new Mellowtel(configurationKey, options?)`で作成したインスタンスで利用可能です。

**ライフサイクル**

* `init(): Promise<void>`は、ユーザーがオプトインしている場合にサービスを開始し、そうでない場合は静かに早期にリターンします。設定キーが空の場合のみスローします。
* `requestConsent(window: BrowserWindow, incentive: string): Promise<boolean | undefined>`は、組み込みのネイティブ同意ダイアログを表示し、結果を保持します。承諾時に`true`、拒否または閉じた場合に`false`、すでに同意が与えられている場合に`undefined`を返します。
* `showConsentSettings(window: BrowserWindow): Promise<void>`は、組み込みの同意管理ダイアログを表示します。ユーザーが選択を切り替えたときに、SDKは内部的にオプトイン/オプトアウトの遷移を処理します。

**手動オプトイン制御**

* `optIn(): Promise<void>`は、ダイアログを表示せずにユーザーをオプトインとしてフラグします。独自のUIを通じて同意を収集した後にのみ使用します。
* `optOut(): Promise<void>`は、ユーザーをオプトアウトとしてフラグし、アクティブなWebSocket接続を閉じます。
* `getOptInStatus(): boolean | undefined`は、現在のオプトイン状態を返します。ユーザーが選択をしたことがない場合は`undefined`を返します。
* `getNodeId(): string`は、このインストールのMellowtelノード識別子を返します。サポートチケットを提出する際に便利です。

**リクエストカウンター**

リクエスト数は`electron-store`を通じてローカルに保持され、アプリの再起動後も持続します。ユーザーにオプトインの影響を示したい場合は、独自のUIで表示します。

* `getTotalRequestCount(): number`は、インストール以来処理された総リクエスト数を返します。
* `getDailyRequestCount(): number`は、今日処理されたリクエスト数を返します。
* `getRequestCountForDate(date: string): number`は、特定の日付`YYYY-MM-DD`のカウントを返します。
* `getDailyRequestsHistory(): { [date: string]: number }`は、すべての日別カウントをマップとして返します。
* `getRequestCountsInRange(startDate: string, endDate: string): { [date: string]: number }`は、日付範囲のカウントを返します。
* `getRequestCounts(): { total: number; daily: number; dailyHistory: { [date: string]: number } }`は、3つのカウンターすべてを1回の呼び出しで返します。

***

## シャットダウンとライフサイクル

Electron SDKは**独自の**`before-quit`または`will-quit`ハンドラを登録しません。Electronプロセスが終了すると、バックグラウンドのWebSocket接続も一緒に終了し、明示的なクリーンアップは不要です。

セッション中にMellowtelを切断したい場合（例えば、アプリ内で「一時停止」設定をユーザーが切り替えたとき）、`optOut()`を呼び出します。これにより、オプトインフラグがクリアされ、アクティブな接続が閉じられます。再接続するには、`optIn()`と`init()`を続けて呼び出します。

## 同意の持続性

オプトイン状態は、プラットフォームデフォルトの`electron-store`設定パスに保存されます：

* macOS: `~/Library/Application Support/<YourAppName>/config.json`
* Windows: `%APPDATA%\<YourAppName>\config.json`
* Linux: `~/.config/<YourAppName>/config.json`

状態はアプリの更新後も持続します。アプリをアンインストールしても、アンインストーラーがアプリの設定ディレクトリを明示的に削除しない限り、自動的にはクリアされません。

***

## トラブルシューティング

<AccordionGroup>
  <Accordion title="&#x22;パッケージが見つかりません&#x22;エラーがインストール中に発生">
    1. `.npmrc`がプロジェクトのルートにあり、`package.json`の隣にあることを確認します。
    2. トークンに前後の空白がないことを確認します。
    3. npmキャッシュをクリアし、`npm cache clean --force`を実行した後に`npm install`を再試行します。
  </Accordion>

  <Accordion title="&#x22;Unauthorized&#x22;または401がインストール中に発生">
    1. `.npmrc`内のトークンが正しくアクティブであることを確認します。不明な場合は、[info@mellowtel.com](mailto:info@mellowtel.com)から新しいトークンをリクエストします。
    2. `@mellowtel-inc:registry`行が存在し、`https://npm.pkg.github.com/`を指していることを確認します。
  </Accordion>

  <Accordion title="同意ダイアログが表示されない">
    1. `app.whenReady()`が解決された**後に**、有効で破棄されていない`BrowserWindow`参照で`requestConsent`を呼び出していることを確認します。
    2. `setupMellowtelApp()`を使用する場合は、`app.whenReady()`の**前に**呼び出していることを確認します。
  </Accordion>

  <Accordion title="&#x22;init()がエラーなしで実行されるが何も起こらない&#x22;">
    これは設計によるものです。ユーザーがオプトインしていない場合、`init()`は静かに早期にリターンします。`getOptInStatus()`を確認してください。`undefined`または`false`を返す場合は、まず`requestConsent`を実行します。内部の「ユーザーがオプトインしていない」ログは、`disableLogs`がデフォルトのままの場合には抑制されるため（下記「ログが静か」参照）、ターミナルはフラグを反転するまでどちらの信号も与えません。
  </Accordion>

  <Accordion title="ログが静か">
    `disableLogs`コンストラクタオプションはデフォルトで`true`です。統合中は、接続状態とリクエスト活動をターミナルに表示するために、コンストラクタの第2引数として`{ disableLogs: false }`を渡します。これは「オプトインしていない」静かなノーオペ（上記参照）と実際の接続失敗を区別する最速の方法でもあります。
  </Accordion>
</AccordionGroup>

***

完了までの推定時間：10〜15分。

ヘルプが必要な場合やフィードバックがある場合は、[info@mellowtel.com](mailto:info@mellowtel.com)までご連絡いただくか、[Discordコミュニティ](https://discord.com/invite/txAZp4MSDe)に参加してください。