This guide will walk you through the process of setting up and utilizing the SDK within your project.

info

Don't forget to generate your Appsalt SDK API Key and download SDK from Developers dashboard first.

Installation

First, ensure you have Node.js and npm installed on your development environment. Then, use npm to install the Appsalt Electron SDK from the Appsalt package registry:

npm install ./appsalt-electron-sdk-v*.tgz

Integration Steps

1. Create SDK Instance

Initialize the Appsalt Electron SDK by creating a new instance with your api key:

import { Appsalt } from "@appsalt/electron-sdk";

const sdk = new Appsalt({
  apiKey: "<your api key here>",
  enableLogging: true,
  loggerCallback: (message) => console.log(message)
});

2. Bind Methods in Main Process

Within your Electron main process (typically in your main.js or main.ts file), bind methods to handle SDK operations and events using Electron's ipcMain:

import { ipcMain } from "electron";

ipcMain.handle("appsalt:start", () => sdk.start());
ipcMain.handle("appsalt:stop", () => sdk.stop());
ipcMain.handle("appsalt:request-consent", () => sdk.requestConsent());
ipcMain.handle("appsalt:is-running", () => sdk.isRunning);
ipcMain.handle("appsalt:is-opted-in", () => sdk.isOptedIn);
ipcMain.handle("appsalt:opt-in", () => sdk.optIn());
ipcMain.handle("appsalt:opt-out", () => sdk.optOut());
ipcMain.handle("appsalt:identify", () => sdk.identify());;

sdk.on("is-running", (isRunning) => {
  if(!mainWindow || mainWindow.isDestroyed() || !mainWindow.webContents || mainWindow.webContents.isDestroyed()) {
    return;
  }
  mainWindow.webContents.send("appsalt:is-running", isRunning);
});

sdk.on("is-opted-in", (isOptedIn) => {
  if(!mainWindow || mainWindow.isDestroyed() || !mainWindow.webContents || mainWindow.webContents.isDestroyed()) {
    return;
  }
  mainWindow.webContents.send("appsalt:is-opted-in", isOptedIn);
});

3. Bind Methods in Preload Script (Renderer Process)

In the preload script of your Electron renderer process (typically a script linked in your Electron BrowserWindow settings), expose SDK functionality to the frontend using Electron's contextBridge:

import { contextBridge, ipcRenderer } from "electron";

const AppsaltBridge = {
  start: () => ipcRenderer.invoke("appsalt:start"),
  stop: () => ipcRenderer.invoke("appsalt:stop"),
  requestConsent: () => ipcRenderer.invoke("appsalt:request-consent"),
  isRunning: () => ipcRenderer.invoke("appsalt:is-running"),
  isOptedIn: () => ipcRenderer.invoke("appsalt:is-opted-in"),
  optIn: () => ipcRenderer.invoke("appsalt:opt-in"),
  optOut: () => ipcRenderer.invoke("appsalt:opt-out"),
  identify: () => ipcRenderer.invoke("appsalt:identify"),

  changeConsent: (consent: boolean) =>
    ipcRenderer.send("appsalt:change-consent", consent),
  onIsRunningChange: (callback: (status: boolean) => void) => {
    ipcRenderer.on("appsalt:is-running", (_event, isRunning) => {
      callback(isRunning);
    });
  },
  onIsOptedInChange: (callback: (status: boolean) => void) => {
    ipcRenderer.on("appsalt:is-opted-in", (_event, isOptedIn) => {
      callback(isOptedIn);
    });
  },
};

contextBridge.exposeInMainWorld("AppsaltBridge", AppsaltBridge);

4. Usage in Renderer Process (Frontend)

Now you can use the exposed Appsalt object in your renderer process to interact with the Appsalt Electron SDK:

window.AppsaltBridge.start(); // Start the SDK
window.AppsaltBridge.stop(); // Stop the SDK
window.AppsaltBridge.isRunning(); // Check if the SDK is running
window.AppsaltBridge.isOptedIn(); // Check if consent is given
window.AppsaltBridge.optIn(); // Give consent
window.AppsaltBridge.optOut(); // Revoke consent
window.AppsaltBridge.requestConsent(); // Open the consent window if needed
window.AppsaltBridge.identify(); // Get SDK ID

window.AppsaltBridge.onIsRunningChange((status) => {
  console.log("SDK status changed:", status);
}); // Listen for SDK status changes
window.AppsaltBridge.onIsOptedInChange((status) => {
  console.log("Opt in changed:", status);
}); // Listen for consent changes

Additional Notes

• Consent Management: Ensure that you handle consent appropriately based on user interactions and local regulations.
• Error Handling: Implement error handling for SDK operations to provide a smooth user experience.
• Customization: Contact the Appsalt team for customization requests or further assistance with integrating the SDK.

By following these steps, you'll successfully integrate and utilize the Appsalt Electron SDK in your Electron application. If you have any questions or encounter issues during integration, please reach out to us at [email protected] for support. Happy coding!