v1 on SweetJuice Docs

Overview

Mon, 20 Jul 2026 16:48:39 +0000

Version: 1.6

Sweet Juice is an open-source Go mobile app development framework for building native mobile apps using Go and native Android/iOS components, powered by gomobile.

Features

Fast and optimised compile times.
Deep Native integrations.
Supports cross-platform builds for Android apps on Linux, Windows and macOS.
Supports cross-platform builds for iOS apps on Linux, Windows and macOS.

GET STARTED WITH TUTORIALS WITH THE BUTTON BELOW

Getting started

Mon, 20 Jul 2026 16:48:39 +0000

This document contains the installation, bootstrapping, build and uninstall steps used during development.

Prerequisites

Go 1.24+
Android SDK and Android NDK installed (Android Studio recommended)
xtool.sh (For cross-platform iOS builds)
git, curl

NB: For less mess, do not alter the default location for Android SDK.

Installation

You can use Go to install Sweet Juice CLI tool, juice.

Using Go:

go install github.com/sweet-juice/sweetjuice/cmd/juice@latest

Create a new project

juice --new my-new-app

This scaffolds a fresh project from the local AppTemplate included in the Sweet Juice module.

Build Your First App

Fri, 07 Aug 2026 13:08:00 +0000

1. Scaffold

juice --new MyApp
cd MyApp

2. Define state

lib/state/app_state.go

package state

type MainAppState struct {
    SelectedTab string
}

func NewMainAppState() *MainAppState {
    return &MainAppState{SelectedTab: "feed"}
}

func (s *MainAppState) SetSelectedTab(tab string) {
    s.SelectedTab = tab
}

3. Build the UI

lib/views/home_view.go

package views

import (
    "myapp/lib/state"
    "github.com/sweet-juice/sweetjuice/plugins/mu3"
    "github.com/sweet-juice/sweetjuice/ui"
    "github.com/sweet-juice/sweetjuice/ui/style"
)

type HomeView struct {
    State *state.MainAppState
}

func (v *HomeView) Render() ui.Node {
    return ui.Root(
        ui.VStack(
            mu3.TopAppBar("Feed", "menu"),
            ui.Spacer().Height(12),
            mu3.SearchBar("Search...", false),
            ui.Spacer().Height(16),
            mu3.Tabs([]string{"For You", "Saved", "Archived"}, nil, v.State.SelectedTab).
                OnChanged(v.State.SetSelectedTab),
            ui.Spacer().Height(16),
            v.contentForTab(),
            ui.Spacer().Height(24),
            mu3.NavigationBar([]map[string]string{
                {"label": "Home", "icon": "home"},
                {"label": "Explore", "icon": "explore"},
                {"label": "Profile", "icon": "person"},
            }),
        ),
        "#FFFBFE",
    )
}

func (v *HomeView) contentForTab() ui.Node {
    switch v.State.SelectedTab {
    case "saved":
        return ui.VStack(
            mu3.Card("Saved", "Item 1").OnClick(func() { println("saved") }),
            ui.Spacer().Height(12),
            mu3.Card("Saved", "Item 2").OnClick(func() { println("saved") }),
        )
    default:
        return ui.VStack(
            mu3.Card("Feed", "Welcome to Sweet Juice").OnClick(func() { println("feed") }),
            ui.Spacer().Height(12),
            mu3.Card("Feed", "Material You is active").OnClick(func() { println("feed") }),
        )
    }
}

4. Bootstrap

start.go

Plugins

Fri, 07 Aug 2026 13:08:00 +0000

Sweet Juice plugins are first-party bridges between Go and native Android system APIs.

Plugin guides

Permissions Plugin — Check and request runtime permissions.
Notification Plugin — Post and cancel system notifications.
Calls Plugin — Read device call history.
SMS Plugin — Read SMS messages from inbox, sent, and drafts.
WorkManager Plugin — Schedule background tasks.
Special Permissions Plugin — Accessibility, battery exemption, notification access, and more.
Notification Listener Plugin — React to notifications posted or removed by any app.
DataDir Plugin — Read/write app internal storage and access standard directories.

More plugins are documented as they are stabilized and stress-tested.

Writing Plugins

Fri, 07 Aug 2026 13:08:00 +0000

A Sweet Juice plugin has two parts:

Go side — exposes a friendly API and calls core.CallNativePlatform to reach native code.
Native side — implements SweetJuicePlugin, registers widget factories, and handles actions.

Go-side plugin

package myplugin

import (
    "encoding/json"
    "github.com/sweet-juice/sweetjuice/core"
)

type Plugin struct {
    app *core.Application
}

func NewPlugin() *Plugin {
    return &Plugin{}
}

func (p *Plugin) Init(app *core.Application) error {
    p.app = app
    // Register native callbacks if needed
    app.RegisterNativeMethod("myplugin:result", func(args []json.RawMessage) (interface{}, error) {
        // handle result from native side
        return map[string]string{"status": "ok"}, nil
    })
    return nil
}

func (p *Plugin) DoSomething(input string) (string, error) {
    payload, _ := json.Marshal(map[string]string{"input": input})
    return core.CallNativePlatform("myplugin:doSomething", payload), nil
}

Native-side plugin (Android)

package com.sweetjuice.pkg.myplugin;

import android.content.Context;
import com.sweetjuice.plugin.SweetJuicePlugin;
import org.json.JSONObject;
import org.json.JSONException;

public class MyPlugin implements SweetJuicePlugin {
    private Context mContext;

    @Override
    public String getDomain() { return "myplugin"; }

    @Override
    public void onAttach(Context context) {
        this.mContext = context;
    }

    @Override
    public String handleAction(String action, String jsonArgsPayload) {
        try {
            JSONObject args = new JSONObject(jsonArgsPayload);
            if ("doSomething".equals(action)) {
                String input = args.optString("input", "");
                // do native work
                return "{\"result\":\"" + input + "\"}";
            }
            return "{\"error\":\"Unknown action\"}";
        } catch (JSONException e) {
            return "{\"error\":\"" + e.getMessage() + "\"}";
        }
    }
}

Register the plugin

Add the plugin to SweetJuiceApplication:

Notification Plugin

Mon, 10 Aug 2026 04:54:00 +0000

The Notification plugin lets your app post and cancel system notifications on Android.

Setup

The notification plugin is already registered in the default AppTemplate.

Android Manifest

<uses-permission android:name="android.permission.POST_NOTIFICATIONS" />

API

`notification.NewPlugin() *NotificationPlugin`

Creates a new notification plugin instance.

`(*NotificationPlugin).Post(n Notification) (string, error)`

Posts a system notification.

Returns: A result string from the native layer, typically {"status":"posted"} or similar.

`(*NotificationPlugin).Cancel(id int) string`

Cancels a previously posted notification by its ID.

Types

`Notification`

type Notification struct {
    ID          int        `json:"id"`
    Title       string     `json:"title"`
    Body        string     `json:"body"`
    ChannelID   string     `json:"channel_id"`
    ChannelName string     `json:"channel_name"`
    Importance  Importance `json:"importance"`
}

Field	Description
`ID`	Notification ID. If `0`, a unique ID is generated automatically
`Title`	Notification title text
`Body`	Notification body text
`ChannelID`	Android notification channel ID. Defaults to `default_channel`
`ChannelName`	Human-readable channel name. Defaults to `General Notifications`
`Importance`	Notification priority level

`Importance`

type Importance string

const (
    ImportanceDefault Importance = "DEFAULT"
    ImportanceHigh    Importance = "HIGH"
    ImportanceLow     Importance = "LOW"
    ImportanceMin     Importance = "MIN"
)

Example

import "github.com/sweet-juice/sweetjuice/plugins/notification"

plugin := notification.NewPlugin()

_, err := plugin.Post(notification.Notification{
    Title:       "Sweet Juice",
    Body:        "Background sync running...",
    ChannelID:   "default_channel",
    ChannelName: "General Notifications",
    Importance:  notification.ImportanceDefault,
})

// Cancel a notification by ID
plugin.Cancel(12345)

Notes

On Android 13+ (API 33), the user must grant POST_NOTIFICATIONS runtime permission before notifications can be posted.
The notification plugin uses a default channel if none is specified. Custom channels should be created natively if you need different behavior.

Writing Android Plugins

Fri, 07 Aug 2026 13:08:00 +0000

Android plugins live under:

plugins/<name>/android/com/sweetjuice/pkg/<name>/

And are synced into the template at:

AppTemplate/native/android/app/src/main/java/com/sweetjuice/pkg/<name>/

Plugin contract

Every plugin must implement SweetJuicePlugin:

public class MyPlugin implements SweetJuicePlugin {
    @Override
    public String getDomain() { return "mydomain"; }

    @Override
    public void onAttach(Context context) { }

    @Override
    public String handleAction(String action, String jsonArgsPayload) {
        // route action to handler
        return "{}";
    }
}

Action routing

handleAction receives the action name and a JSON payload. Use it to route to specific handlers:

@Override
public String handleAction(String action, String jsonArgsPayload) {
    try {
        JSONObject args = new JSONObject(jsonArgsPayload);
        switch (action) {
            case "check":
                return check(args);
            case "request":
                return request(args);
            default:
                return errorJson("Unknown action");
        }
    } catch (JSONException e) {
        return errorJson(e.getMessage());
    }
}

Returning results

Return JSON strings. The Go side receives the raw string and unmarshals it:

Calls Plugin

Fri, 07 Aug 2026 13:08:00 +0000

The Calls plugin provides read-only access to the device call log.

Setup

The calls plugin is already registered in the default AppTemplate.

Android Manifest

<uses-permission android:name="android.permission.READ_CALL_LOG" />

API

`calls.GetRecent(limit int) (CallLog, error)`

Fetches the most recent call log entries.

Returns: CallLog containing Calls and Count

`calls.GetLast(limit int) (CallLog, error)`

An alias for GetRecent(limit).

`calls.GetAll() (CallLog, error)`

Fetches the entire call log.

Returns: CallLog or error

Types

`CallLog`

type CallLog struct {
    Calls []CallRecord `json:"calls"`
    Count int          `json:"count"`
}

`CallRecord`

Field	Type	Description
`ID`	`int64`	Stable row ID
`Number`	`string`	Phone number or URI
`Type`	`string`	`"incoming"`, `"outgoing"`, `"missed"`, etc.
`Date`	`int64`	Epoch millis
`Duration`	`int64`	Duration in seconds
`CachedName`	`string`	Contact name if available
`GeoLocation`	`string`	Reverse-geocoded location if available

Events

`calls:changed`

Emitted when the native side detects a call-log change.

Permissions Plugin

Fri, 07 Aug 2026 13:08:00 +0000

The Permissions plugin provides a thin, reliable bridge between Go and the Android runtime permission system.

Setup

The permissions plugin is already registered in the default AppTemplate.

API

`permission.Check(permission string) (string, error)`

Returns the current status of a single permission.

`permission.Request(permission string) (string, error)`

Shows the system permission dialog.

`permission.RequestMultiple(permissions []string) (string, error)`

Requests multiple permissions sequentially.

Events

`permissions:changed`

Emitted each time a permission request completes.

{
  "permission": "android.permission.READ_CALL_LOG",
  "granted": true
}

Example

import "github.com/sweet-juice/sweetjuice/plugins/permission"

status, _ := permission.RequestMultiple([]string{
    "android.permission.READ_CALL_LOG",
    "android.permission.READ_SMS",
})

SMS Plugin

Fri, 07 Aug 2026 13:08:00 +0000

The SMS plugin provides read-only access to device SMS messages across inbox, sent, and draft folders.

Setup

The SMS plugin is already registered in the default AppTemplate.

Android Manifest

<uses-permission android:name="android.permission.READ_SMS" />

Note: On Android 4.4+ (KITKAT), this plugin can only read SMS messages if your app is the default SMS app.

API

`sms.GetRecent(limit int) (SmsFolder, error)`

Fetches the most recent SMS messages across all folders.

Returns: SmsFolder or error

WorkManager Plugin

Sun, 09 Aug 2026 15:44:00 +0000

The WorkManager plugin manages background tasks via the Android WorkManager API, supporting constraint-based one-time and periodic scheduling.

Setup

The WorkManager plugin is already registered in the default AppTemplate.

Android Manifest

<uses-permission android:name="android.permission.FOREGROUND_SERVICE" />
<uses-permission android:name="android.permission.FOREGROUND_SERVICE_SPECIAL_USE" />

API

`workmanager.NewPlugin() *WorkManagerPlugin`

Creates a new WorkManager plugin instance.

`(*WorkManagerPlugin).RegisterTask(name string, fn TaskFunc)`

Registers a task function that can be executed by WorkManager.

type TaskFunc func() error

`(WorkManagerPlugin).EnqueueOneTime(taskKey string, constraints Constraints) (string, error)`

Schedules a one-time background task.

`(WorkManagerPlugin).EnqueuePeriodic(taskKey string, intervalMinutes int, constraints Constraints, replaceExisting bool, runImmediate bool) (string, error)`

Schedules a repeating background task using enqueueUniquePeriodicWork.

Special Permissions Plugin

Sun, 09 Aug 2026 15:44:00 +0000

The Special Permissions plugin handles Android permissions that cannot be requested through normal runtime dialogs. These require the user to manually enable them in system settings.

Setup

The special permissions plugin is already registered in the default AppTemplate.

API

`special.Request(perm SpecialType) (string, error)`

Opens the system settings screen for the given permission type.

`special.Check(perm SpecialType) (bool, error)`

Checks whether the given special permission is currently granted.

Special Permission Types

Type	Settings Screen	Android Version
`Accessibility`	`Settings.ACTION_ACCESSIBILITY_SETTINGS`	All
`AllFilesAccess`	`Settings.ACTION_MANAGE_APP_ALL_FILES_ACCESS_PERMISSION`	11+
`BatteryExemption`	`Settings.ACTION_REQUEST_IGNORE_BATTERY_OPTIMIZERS`	6.0+
`NotificationAccess`	`Settings.ACTION_NOTIFICATION_LISTENER_SETTINGS`	All

Convenience Helpers

Function	Description
`RequestAccessibility() (string, error)`	Opens Accessibility settings
`RequestAllFilesAccess() (string, error)`	Opens All Files Access settings (Android 11+)
`RequestBatteryExemption() (string, error)`	Opens battery optimization exemption dialog
`RequestNotificationAccess() (string, error)`	Opens notification access settings
`RequestAppSettings() (string, error)`	Opens app-specific system settings
`CheckAccessibility() (bool, error)`	Checks if Accessibility is granted
`CheckAllFilesAccess() (bool, error)`	Checks if All Files Access is granted
`CheckBatteryExemption() (bool, error)`	Checks if battery exemption is granted
`CheckNotificationAccess() (bool, error)`	Checks if notification access is granted

Example

import "github.com/sweet-juice/sweetjuice/plugins/special"

// Request battery exemption
special.RequestBatteryExemption()

// Request notification access
special.RequestNotificationAccess()

// Check if notification access is granted
granted, _ := special.CheckNotificationAccess()

Android Notes

These permissions cannot be requested via requestPermissions().
The user must manually enable them in the system settings screen.
AllFilesAccess requires Android 11 (API 30) or higher.
NotificationAccess requires a NotificationListenerService declared in the app manifest with the BIND_NOTIFICATION_LISTENER_SERVICE permission.

Notification Listener Plugin

Sun, 09 Aug 2026 15:44:00 +0000

The Notification Listener plugin receives callbacks when notifications are posted or removed on the device. It lets your Go code react to incoming notifications from any app.

Setup

The notification listener plugin is already registered in the default AppTemplate.

Android Manifest

The app must declare a NotificationListenerService and the user must grant notification access in system settings.

<service
    android:name="com.sweetjuice.pkg.notifications.SweetJuiceNotificationListener"
    android:label="@string/app_name"
    android:permission="android.permission.BIND_NOTIFICATION_LISTENER_SERVICE"
    android:exported="false">
    <intent-filter>
        <action android:name="android.service.notification.NotificationListenerService" />
    </intent-filter>
</service>

Use the Special Permissions plugin to open the notification access settings screen:

DataDir Plugin

Sun, 09 Aug 2026 20:05:00 +0000

The DataDir plugin provides access to standard Android application directories and supports reading and writing files within internal storage.

Setup

The datadir plugin is already registered in the default AppTemplate.

API

`datadir.NewPlugin() *DataDirPlugin`

Creates a new datadir plugin instance.

`(*DataDirPlugin).GetDirs() (AppDirs, error)`

Returns the application directory paths.

type AppDirs struct {
    Files         string // Internal files directory
    Cache         string // Internal cache directory
    ExternalFiles string // External files directory (if available)
    ExternalCache string // External cache directory (if available)
}

`(*DataDirPlugin).ReadFile(path string) (string, error)`

Reads the contents of a file from the internal files directory.

System Plugin

Wed, 12 Aug 2026 09:00:00 +0000

The System plugin provides comprehensive OS and device information.

Setup

The system plugin is already registered in the default AppTemplate.

API

`system.NewPlugin() *SystemPlugin`

Creates a new System plugin instance.

`(*SystemPlugin).GetInfo() (SystemInfo, error)`

Returns OS and device information from the native layer.

Returns: SystemInfo struct or error.

Types

`SystemInfo`

type SystemInfo struct {
    SystemName          string `json:"system_name"`
    SystemVersion       string `json:"system_version"`
    Model               string `json:"model"`
    SdkInt              int    `json:"sdk_int"`
    Release             string `json:"release"`
    Codename            string `json:"codename"`
    Manufacturer        string `json:"manufacturer"`
    Brand               string `json:"brand"`
    Board               string `json:"board"`
    Device              string `json:"device"`
    Product             string `json:"product"`
    Hardware            string `json:"hardware"`
    BaseOS              string `json:"base_os"`
    SecurityPatch       string `json:"security_patch"`
    Name                string `json:"name"`
    LocalizedModel      string `json:"localized_model"`
    IdentifierForVendor string `json:"identifier_for_vendor"`
    IsPhysicalDevice    bool   `json:"is_physical_device"`
}

Field	Platform	Description
`system_name`	All	`"Android"` or `"iOS"`
`system_version`	All	Human-readable OS version
`model`	All	Device model name
`manufacturer`	Android	`Build.MANUFACTURER`
`brand`	Android	`Build.BRAND`
`release`	Android	`Build.VERSION.RELEASE`
`sdk_int`	Android	`Build.VERSION.SDK_INT`
`security_patch`	Android	Security patch level
`is_physical_device`	All	Whether the app is running on a real device

Example

import "github.com/sweet-juice/sweetjuice/plugins/system"

plugin := system.NewPlugin()
info, err := plugin.GetInfo()
if err == nil {
    fmt.Printf("Device: %s %s\n", info.Manufacturer, info.Model)
    fmt.Printf("OS: %s %s\n", info.SystemName, info.SystemVersion)
}

Broadcast Plugin

Wed, 12 Aug 2026 15:00:00 +0000

The Broadcast plugin provides a bridge to the Android system’s Intent-based broadcast infrastructure.

Setup

The broadcast plugin is already registered in the default AppTemplate.

API

`broadcast.On(action string, callback func(interface{}))`

Registers a handler for a specific Android Intent action.

When the OS fires a matching intent, the plugin captures it and forwards the extras as a Go map to your callback.

`broadcast.Post(action string, extras map[string]interface{})`

Sends a system-wide broadcast (Intent) on the native side.

v1 on SweetJuice Docs

Overview

Features

Getting started

Prerequisites

Installation

Create a new project

Build Your First App

1. Scaffold

2. Define state

3. Build the UI

4. Bootstrap

Plugins

Plugin guides

Writing Plugins

Go-side plugin

Native-side plugin (Android)

Register the plugin

Notification Plugin

Setup

Android Manifest

API

notification.NewPlugin() *NotificationPlugin

(*NotificationPlugin).Post(n Notification) (string, error)

(*NotificationPlugin).Cancel(id int) string

Types

Notification

Importance

Example

Notes

Writing Android Plugins

Plugin contract

Action routing

Returning results

Calls Plugin

Setup

Android Manifest

API

calls.GetRecent(limit int) (CallLog, error)

calls.GetLast(limit int) (CallLog, error)

calls.GetAll() (CallLog, error)

Types

CallLog

CallRecord

Events

calls:changed

Permissions Plugin

Setup

API

permission.Check(permission string) (string, error)

permission.Request(permission string) (string, error)

permission.RequestMultiple(permissions []string) (string, error)

Events

permissions:changed

Example

SMS Plugin

Setup

Android Manifest

API

sms.GetRecent(limit int) (SmsFolder, error)

WorkManager Plugin

Setup

Android Manifest

API

workmanager.NewPlugin() *WorkManagerPlugin

(*WorkManagerPlugin).RegisterTask(name string, fn TaskFunc)

(*WorkManagerPlugin).EnqueueOneTime(taskKey string, constraints *Constraints) (string, error)

(*WorkManagerPlugin).EnqueuePeriodic(taskKey string, intervalMinutes int, constraints *Constraints, replaceExisting bool, runImmediate bool) (string, error)

Special Permissions Plugin

Setup

API

special.Request(perm SpecialType) (string, error)

special.Check(perm SpecialType) (bool, error)

Special Permission Types

Convenience Helpers

Example

Android Notes

Notification Listener Plugin

Setup

Android Manifest

`notification.NewPlugin() *NotificationPlugin`

`(*NotificationPlugin).Post(n Notification) (string, error)`

`(*NotificationPlugin).Cancel(id int) string`

`Notification`

`Importance`

`calls.GetRecent(limit int) (CallLog, error)`

`calls.GetLast(limit int) (CallLog, error)`

`calls.GetAll() (CallLog, error)`

`CallLog`

`CallRecord`

`calls:changed`

`permission.Check(permission string) (string, error)`

`permission.Request(permission string) (string, error)`

`permission.RequestMultiple(permissions []string) (string, error)`

`permissions:changed`

`sms.GetRecent(limit int) (SmsFolder, error)`

`workmanager.NewPlugin() *WorkManagerPlugin`

`(*WorkManagerPlugin).RegisterTask(name string, fn TaskFunc)`

`(WorkManagerPlugin).EnqueueOneTime(taskKey string, constraints Constraints) (string, error)`

`(WorkManagerPlugin).EnqueuePeriodic(taskKey string, intervalMinutes int, constraints Constraints, replaceExisting bool, runImmediate bool) (string, error)`

`special.Request(perm SpecialType) (string, error)`

`special.Check(perm SpecialType) (bool, error)`

`datadir.NewPlugin() *DataDirPlugin`

`(*DataDirPlugin).GetDirs() (AppDirs, error)`

`(*DataDirPlugin).ReadFile(path string) (string, error)`

`system.NewPlugin() *SystemPlugin`

`(*SystemPlugin).GetInfo() (SystemInfo, error)`

`SystemInfo`

`broadcast.On(action string, callback func(interface{}))`

`broadcast.Post(action string, extras map[string]interface{})`