Desktop setup guide

Build and launch Sngine Messenger on macOS and Windows.

This guide covers the developer machine setup, Flutter desktop commands, release builds, branding assets, operating system permissions, and final checks needed before delivering the desktop messenger to customers.

Flutter stable macOS desktop Windows desktop Release build
2 platforms Native desktop builds for macOS and Windows.
Desktop addon Upload the desktop API addon into the Sngine script root.
Release ready Includes packaging, permissions, and launch checks.
Customer safe Steps are written for handoff and repeated installation.

Requirements

Prepare the tools below before opening the project.

1

Flutter SDK

Install the current stable Flutter SDK and make sure the `flutter` command is available in your terminal.

Official Flutter install guide

2

Desktop toolchain

macOS requires Xcode tools. Windows requires Visual Studio with the desktop C++ workload.

Flutter desktop support

3

Project package

Extract the Messenger desktop source package into a clean working folder before running commands.

flutter --version
flutter doctor -v

Install Flutter for macOS desktop

Install Apple tools

xcode-select --install
sudo xcodebuild -license accept

Open Xcode once after installation so macOS finishes the first-run setup.

Enable macOS desktop

flutter config --enable-macos-desktop
flutter doctor -v

Fix every macOS item reported by `flutter doctor` before building a release.

Install Flutter for Windows desktop

Install Visual Studio

Install Visual Studio 2022 and select the “Desktop development with C++” workload.

Enable Windows desktop

flutter config --enable-windows-desktop
flutter doctor -v

Run the commands from PowerShell, Windows Terminal, or Command Prompt.

Open the project

After extracting the desktop source package, run the setup commands from the project root.

cd sangine-messanger-dsktop
flutter clean
flutter pub get
flutter analyze

Recommended editor

Use Visual Studio Code, Android Studio, or IntelliJ with Flutter and Dart plugins installed.

Upload the Desktop API Addon to Sngine

The desktop application needs the desktop API addon installed inside the same Sngine script. Upload the folder named api-addon-messanger-desktop to the Sngine root before testing login, conversations, stories, stickers, calls, media, and app settings.

Correct server location

your-sngine-root/
  bootstrap.php
  includes/
  content/
  api-addon-messanger-desktop/
    install.php
    update.php
    index.php
    admin/
    sql/
    seeders/
    assets/

Do not upload here

content/themes/api-addon-messanger-desktop
includes/api-addon-messanger-desktop
api-addon-messanger-desktop/api-addon-messanger-desktop
api-addons/api-addon-messanger-desktop

Upload using File Manager, FTP, or SFTP

  1. Extract the Sngine Messenger Desktop package on your computer.
  2. Find the folder named api-addon-messanger-desktop.
  3. Open the hosting File Manager, FTP client, or SFTP client.
  4. Go to the Sngine root folder. It must contain bootstrap.php, includes, and content.
  5. Upload the full api-addon-messanger-desktop folder into that root folder.
  6. If you upload a ZIP file, extract it in the Sngine root and confirm the folder is not nested twice.
Correct:
https://your-domain.com/api-addon-messanger-desktop/install.php

Wrong:
https://your-domain.com/api-addon-messanger-desktop/api-addon-messanger-desktop/install.php

Install or update the addon

Fresh install

Open the installer, enter the Messenger Desktop purchase code, and complete the checks.

https://your-domain.com/api-addon-messanger-desktop/install.php

Existing installation

After replacing addon files with a newer package, open the update page once.

https://your-domain.com/api-addon-messanger-desktop/update.php

Open the desktop addon dashboard

After install/update, open the admin area to confirm branding, app logo, license status, colors, calls, Agora, and sticker settings. 

https://your-domain.com/api-addon-messanger-desktop/admin/index.php

Folder name matters

Keep the final server folder name as api-addon-messanger-desktop. If your downloaded ZIP has a different outer name, upload or rename only the actual addon folder.

Run on macOS

Use this command while developing and testing the desktop app locally on a Mac.

flutter run -d macos
✓
Confirm the app opens in a native macOS window.
✓
Check microphone, camera, notification, and file download permissions.
✓
Test login, chat list, sending text, attachments, voice notes, calls, and theme switching.

Release for macOS

Build a production macOS app after all local checks pass.

flutter build macos --release

Output folder

build/macos/Build/Products/Release/

Distribution notes

For public distribution, configure signing, notarization, app icon, bundle identifier, and permissions in the macOS runner.

Official macOS release guide

Run on Windows

Use this command while developing and testing the desktop app locally on Windows.

flutter run -d windows
✓
Confirm the native window opens and resizes correctly.
✓
Test microphone, camera, notifications, file picker, and media preview.
✓
Check that long messages, Arabic text, and dark mode render correctly.

Release for Windows

Build the production Windows executable from a Windows machine.

flutter build windows --release

Output folder

build\windows\x64\runner\Release\

Distribution notes

Package the Release folder with the executable and required DLL files. For Microsoft Store release, prepare MSIX packaging and store metadata.

Official Windows release guide

Create a Windows installer

A Windows release should not be delivered as source code. Build a release folder first, then package it as an installer that includes the executable, DLL files, data folder, icon, version, and shortcuts.

What you need on the Windows build machine

Build tools

  • Windows 10 or Windows 11, 64-bit.
  • Flutter stable channel.
  • Visual Studio 2022 with “Desktop development with C++”.
  • Git and a terminal such as PowerShell or Windows Terminal.

Installer tools

  • Inno Setup for a direct .exe installer.
  • MSIX Packaging Tool or the msix workflow for Microsoft Store style packages.
  • A code signing certificate if the app will be released publicly.

Build the Windows release folder

flutter clean
flutter pub get
flutter analyze
flutter build windows --release

The files to package are inside:

build\windows\x64\runner\Release\

Recommended installer options

Direct customer installer

Use Inno Setup when you want to deliver a normal installer from your website or customer portal. Add every file from the Release folder, install to Program Files, create desktop/start menu shortcuts, and use the final app icon.

Official store release

Use MSIX and Microsoft Partner Center for Microsoft Store distribution. Prepare the store identity, publisher information, app name, screenshots, privacy policy, and certification metadata.

Before publishing the installer

✓
Test the installer on a clean Windows machine or virtual machine.
✓
Confirm the installed app opens without needing Flutter or developer tools.
✓
Sign the installer and executable when releasing publicly.
✓
Confirm the app name, icon, version, publisher, and uninstall entry are correct.

Create the license and prepare credentials

Before building a customer release, collect the purchase code from Flutter Crafters Store and the API credentials from the customer’s Sngine admin panel. These values are used to activate the desktop addon and prepare the desktop app connection to the customer website.

Get the purchase code

  1. Open Flutter Crafters My Purchases.
  2. Sign in with the account that purchased Sngine Messenger Desktop.
  3. Open the Messenger Desktop purchase item.
  4. Copy the Purchase Code or License Code.

Get API Key and API Secret

  1. Open the customer Sngine admin panel.
  2. Go to /admincp/apis.
  3. Copy API Key.
  4. Copy API Secret.
Example:
https://sngine-app.fluttercrafters.com/admincp/apis

Create or activate the license

  1. Open license.fluttercrafters.com.
  2. Select the Sngine Messenger Desktop product or license workflow.
  3. Enter the customer domain, for example https://your-domain.com.
  4. Enter the purchase code from Flutter Crafters Store.
  5. Enter the Sngine API Key and API Secret from /admincp/apis when requested.
  6. Generate or activate the license for that domain.
  7. Use the generated license/config output exactly as shown by the license portal before building the release.

Where these values are used

Desktop addon installer

Use the purchase code when opening the desktop addon installer:

https://your-domain.com/api-addon-messanger-desktop/install.php

Desktop app connection

The desktop app connects to the customer Sngine website using the site URL, API Key, and API Secret. Prepare these values before building the customer release package.

Security note

Never publish the API Secret in documentation, screenshots, public tickets, or release notes. Treat it like a password. If it is exposed, regenerate it from the Sngine admin panel and rebuild the app.

Change the logo and desktop app icon

The Messenger Desktop has two different brand assets. The in-app logo is shown inside the Flutter UI and can be loaded from the API when configured. The desktop app icon is the native operating system icon shown in the Dock, Launchpad, Start menu, installer, and taskbar.

In-app logo

Upload the customer logo from the Messenger Desktop addon/admin settings when available. The app will use the API logo URL first. If no remote logo is configured, it falls back to the local file below. 

assets/logo.png
  1. Prepare a transparent PNG logo that works on light and dark backgrounds.
  2. Recommended size: 1200 x 400 px or another wide transparent logo.
  3. Replace assets/logo.png only when you want a built-in fallback logo.
  4. Run flutter clean after replacing the image if the old asset is still cached.

Shared source icon

Start from one square master icon, then export the platform files from it. Use a 1024 x 1024 px PNG with no text that becomes unreadable at small sizes. 

assets/branding/sngine_messenger_desktop_icon_1024.png
  1. Keep the master icon square.
  2. Use enough padding so the icon does not touch the rounded platform mask.
  3. Export macOS PNG sizes and one Windows .ico file from the same master icon.

macOS app icon

Replace every PNG inside the macOS AppIcon set. Keep the existing file names unless you also edit Contents.json. 

macos/Runner/Assets.xcassets/AppIcon.appiconset/app_icon_16.png
macos/Runner/Assets.xcassets/AppIcon.appiconset/app_icon_32.png
macos/Runner/Assets.xcassets/AppIcon.appiconset/app_icon_64.png
macos/Runner/Assets.xcassets/AppIcon.appiconset/app_icon_128.png
macos/Runner/Assets.xcassets/AppIcon.appiconset/app_icon_256.png
macos/Runner/Assets.xcassets/AppIcon.appiconset/app_icon_512.png
macos/Runner/Assets.xcassets/AppIcon.appiconset/app_icon_1024.png
  1. Replace all sizes before building the release app.
  2. Run flutter clean, then flutter build macos --release.
  3. Open the release app and confirm the Dock and Finder icon are updated.

Windows app icon

Windows reads the app icon from the runner resource file. Replace the ICO file before building the release folder and before creating the installer. 

windows/runner/resources/app_icon.ico
windows/runner/Runner.rc
  1. Create an .ico file that includes 16, 32, 48, 64, 128, and 256 px sizes.
  2. Keep the path used by Runner.rc: resources\\app_icon.ico.
  3. Run flutter clean, then flutter build windows --release.
  4. Use the same app_icon.ico in Inno Setup, MSIX, or your installer tool.

Branding checklist

✓
The logo is readable in light mode and dark mode.
✓
The native app icon is replaced before the macOS and Windows release builds.
✓
The Windows installer uses the same icon as the built executable.
✓
The final app is rebuilt after changing any logo or icon asset.

Launch checklist

✓
`flutter analyze` returns no issues.
✓
The api-addon-messanger-desktop folder is uploaded to the Sngine root and install/update has been completed.
✓
The purchase code is copied from store.fluttercrafters.com/my-purchases.
✓
The customer API Key and API Secret are copied from /admincp/apis and used only in the secure release workflow.
✓
The Windows installer is tested on a clean Windows machine before delivery.
✓
macOS build opens, signs correctly, and has the correct app icon and name.
✓
Windows build opens from the Release folder on a clean Windows machine.
✓
Login, conversations, media preview, downloads, voice notes, calls, notifications, dark mode, and language switching are tested.
✓
The final package includes only release files and no local cache, temporary output, or developer-only logs.

Troubleshooting

`flutter` command not found

Add the Flutter SDK `bin` folder to your PATH, restart the terminal, then run `flutter doctor -v` again.

macOS permission blocked

Open System Settings and allow microphone, camera, notifications, or file access for the app.

Windows build tools missing

Modify Visual Studio installation and enable “Desktop development with C++”.

Build cache issue

flutter clean
flutter pub get
flutter build windows --release
Sngine Messenger Desktop Documentation. Updated June 9, 2026.