1. Embedded SDK
Salla Platform Docs
  • Embedded SDK
    • Overview
    • Getting Started
    • Create an Embedded App
    • Authentication
    • App Design Guidelines
    • Installation
    • Playground
  • Auth Module
    • Get Token
    • Client Introspect
    • Refresh Token
  • Page Module
    • External Redirects
    • Navigation
    • Set Page Title
  • Nav Module
    • Create Navbar Action
    • Listen for Navbar Actions
    • Clearing Navbar Actions
    • Add Navbar Item
    • Update Navbar Item
    • Listen for Navbar Item Click
    • Remove Navbar Item
  • UI Module
    • Confirm Dialogs
    • Toast Notifications
    • Loading States
    • Breadcrumbs
  • Checkout Module
    • Create Checkout
    • Get App Add-ons
    • Subscribe for Payment Result
  • Endpoints
    • Token Introspect
      POST
  • Resources
    • Support
    • Common Examples
  • Report Builder
    • Overview
    • Getting Started
    • JMESPath Tutorial
    • Understanding the Report Lifecycle
    • Salla Reports Examples
    • Set up Store data using merchant APIs
    • Report Types
      • Unit
      • Bar
      • Breakdown
      • Calendar
      • Distribution
      • Pipe
      • Plot
      • Ranking
      • Summary
      • Agrid
    • APIs
      • Token Introspect
  • App Onboarding
    • Overview
    • Get Started
    • Interfaces and Responses
    • Example
Merchant
Merchant
  • Merchant API
  • Embedded SDK
  • Salla OAuth 2.0
Storefront
Storefront
  • Twilight Engine
  • Twilight SDK
  • Web Components
  • Ecommerce Events
  • Component Bundle
  • Checkout APIs
  • Change Log
App Functions
Partner APIs
Partner APIs
  • App API
  • Shipments & Fulfillment APIs
  • Salla AWB
  • Recurring Payments API
  • Billing System Salla partners
  • Communication Apps
Dev Tools
Dev Tools
  • Partners Agent Kit
  • Salla Apps Playbook
  • Salla CLI
Merchant
Merchant
  • Merchant API
  • Embedded SDK
  • Salla OAuth 2.0
Storefront
Storefront
  • Twilight Engine
  • Twilight SDK
  • Web Components
  • Ecommerce Events
  • Component Bundle
  • Checkout APIs
  • Change Log
App Functions
Partner APIs
Partner APIs
  • App API
  • Shipments & Fulfillment APIs
  • Salla AWB
  • Recurring Payments API
  • Billing System Salla partners
  • Communication Apps
Dev Tools
Dev Tools
  • Partners Agent Kit
  • Salla Apps Playbook
  • Salla CLI
Salla - Opensource
Salla - Developers Community
  1. Embedded SDK

App Design Guidelines

To provide a seamless and trustworthy experience for merchants, embedded apps should feel like a native extension of the Salla Merchant Dashboard. This guide outlines the visual and functional requirements for designing your app.

What you'll learn:#

The App Design Guidelines:
Key Concepts
Using SDK Components
Visual Identity
Layout and Spacing
Fonts
Embedded App Theme Support

Key Concepts#

SDK Components
Mandatory use of native UI components for core interactions.
Visual Identity
Colors, typography, and iconography from the Salla Brand.
Layout & Spacing
Grid systems and spacing rules for consistent alignment.
Theme Support
Implementing Dark and Light mode synchronization.

Using SDK Components#

Using the Embedded SDK Modules is not just a recommendation—it is a requirement for core dashboard interactions. This ensures that users don't face fragmented UI patterns.

Use Methods, Not Events#

Crucial: Always use the high-level SDK methods (e.g., embedded.ui.toast.success) instead of sending postMessage events directly.
Future Proofing: The internal message structure or event names may change in future versions.
Consistency: SDK methods handle validation and error states that direct events might bypass.
Abstraction: The SDK provides a clean API that hides the complexity of the underlying communication protocol.

Visual Identity#

Your app should adhere to the Salla Brand Guidelines to maintain visual continuity.

Brand Colors#

Salla's core palette defines the look and feel of the Merchant Dashboard. Use these HSL values (or their hex equivalents) for your components to ensure they match the merchant's current theme.
Light Mode
Dark Mode
ColorHSL ValueHex EquivalentUse Case
primary189 100% 17%#004d5bMain brand color, deep teal headings.
secondary163 100% 82%#73fcd7Mint/Teal accents, active states.
success157 100% 34%#00b259Positive feedback, active status.
danger358 89% 64%#f5434aErrors and destructive actions.
bg-main0 0% 97%#f8f8f8Main dashboard workspace background.

Typography#

Salla uses the PingARLT font family for a professional, readable experience across Arabic and English.
Consistency: Ensure your app uses a clean sans-serif stack that matches the dashboard's weight and spacing.

Iconography#

Salla utilizes the Hugeicons library to maintain a clean, geometric, and modern visual language.
Consistency: Use Hugeicons to match the native dashboard aesthetic.
Stroke to Shape: Ensure icons maintain consistent stroke weights. If you are using SVG versions, convert strokes to shapes before scaling to maintain visual integrity.
Native Context: SDK methods will use the same icons. For example setAction allow you to pass icon class names directly. Use the standard Hugeicons class naming convention (e.g., hgi hgi-stroke hgi-star).
Embedded App Banner
It is imperative to add Embedded App Banner image with 1420×520 pxin your App Card for a smooth App publishing journey.
On the Partners Portal, go to My Apps -> Select the App-> App Details -> Start publishing your App-> App Features -> Embedded App Banner.
image.png

Layout & Spacing#

The "No-Chrome" Rule#

Your app runs inside the Salla Dashboard. It should not attempt to replicate the dashboard's navigation or layout.
No Sidebar: Do not include a side navigation menu. Use the dashboard's native app navigation.
No Top Navbar: Do not add a top header or breadcrumbs inside your iframe. Use embedded.page.setTitle() and embedded.nav.setAction() instead.
Full Width: Your content should expand to fill the provided iframe container.

Good vs. Bad Integration#

✅ The Good Integration
❌ The Bad Integration
1.
An integrated app uses native dashboard components and focuses only on its own functional logic.
2.
The app adheres to Salla's Dashboard theme and colors to provide visual consistency and native UI experience.
Integrated App

Salla Fonts#

Use the official Salla Fonts in your embedded apps to ensure a consistent look and feel across the Salla platform.
Available font files:
PingARLT-Regular
PingARLT-Medium
PingARLT-Bold

Embedded App Theme Support#

The Salla Dashboard supports dynamic theme switching (Light & Dark). Your app must respond to these changes.
Syncing: Listen for theme changes using embedded.onThemeChange().
Contrast: Ensure all elements are legible in both light and dark modes by using the dashboard's semantic color variables where possible.

Next Steps#

Create an Embedded App
Browse the full list of available modules to enhance your app's functionality.
Start Developing
Explore the testing playground to boost your embedded app implementation.
Modified at 2026-07-27 12:58:57
Previous
Authentication
Next
Installation