Authentication

Overview

Nosmai Effects requires a valid license key. The key identifies the Nosmai project, the application, the platform, and the features that the application is allowed to use.

Create and manage projects in the Nosmai Console.

A license key uses the following format:

NOSMAI-<project-key>

Initialize the SDK with this key before using the camera, filters, beauty features, recording, or processed live output.

Create a project

The normal setup is:

1. Sign in to the Nosmai Console.
2. Create a project for the application.
3. Add the Android package name or iOS bundle identifier.
4. Select the required platform and product capabilities.
5. Copy the generated license key.
6. Initialize the SDK with that key.

Use the application's final identifier. A key issued for a temporary identifier may stop working after the application is renamed.

Application identity

Nosmai validates the installed application identity.

Android

Android uses the application ID from the app module:

android {
    defaultConfig {
        applicationId = "com.example.cameraapp"
    }
}

The value configured in the Nosmai Console must match the installed application's package name.

Do not use the SDK library namespace as the application identifier. The license belongs to the consuming application.

iOS

iOS uses the bundle identifier configured for the application target:

com.example.cameraapp

The value configured in the Nosmai Console must match the bundle identifier in the signed application.

Flutter

A Flutter application has two native identities:

• the Android package name
• the iOS bundle identifier

Configure both applications correctly in the Nosmai Console. Do not assume that one platform key can automatically be used by the other platform unless the console project explicitly issues and supports that configuration.

Initialize once

Initialize Nosmai once for the current application process.

Flutter

final initialized = await NosmaiFlutter.initialize(
  'NOSMAI-YOUR-LICENSE-KEY',
);

if (!initialized) {
  // Do not open the Nosmai camera screen.
}

iOS

[[NosmaiCore shared]
    initializeWithAPIKey:@"NOSMAI-YOUR-LICENSE-KEY"
              completion:^(BOOL success, NSError *error) {
    if (!success) {
        NSLog(@"Nosmai initialization failed: %@", error.localizedDescription);
    }
}];

Android

NosmaiSDK.initialize(
    applicationContext,
    "NOSMAI-YOUR-LICENSE-KEY"
);

Do not initialize the SDK from a list item, widget build method, frame callback, or every camera-screen appearance.

What verification checks

License verification can check:

• license key format
• project status
• application package name or bundle identifier
• platform
• license validity
• enabled product capabilities
• signed license response

If the supplied key belongs to another application, the cached license for that other key is not reused.

Network behavior

The device needs access to the Nosmai licensing service for the first successful verification.

After a successful verification:

1. the signed license result is stored securely on the device
2. the cache can be used for up to 24 hours
3. if the cache has expired and the network is temporarily unavailable, the SDK can use a further 24-hour offline grace period
4. after the cache and grace period are both exhausted, the device must reconnect and verify again

The cache is tied to the license key. Supplying a different key does not make the previous key's cached result valid.

[!NOTE] The exact license policy may change by SDK version or commercial plan. Applications should handle license status changes instead of assuming that cached access is permanent.

License verification and camera frames

License verification sends application and license information to the Nosmai licensing service. It does not require uploading every camera frame.

Real-time filters, beauty, face tracking, and background processing run on the device. Cloud filter listing and filter downloads use separate network requests.

Temporary network failures

A temporary DNS failure, timeout, or unavailable network does not always mean the license key is invalid.

Treat these cases differently:

Do not show "invalid license" to a user when the actual failure is a temporary network error. Record the technical error and present a retry action.

Development and production keys

Use separate projects or keys for development and production.

This separation prevents:

• a test build using production access by accident
• an internal package name failing against a production key
• unclear usage reporting
• development changes affecting a released application

Store keys safely

A mobile license key must be included in the installed application so the SDK can initialize. It should not be treated like a backend password that can never reach a device.

Still follow these rules:

• do not commit production keys to a public repository
• do not place keys in screenshots, tutorials, issue reports, or public sample apps
• use build configuration or environment files for internal development
• keep development and production keys separate
• rotate a key through the Nosmai Console if it is exposed unexpectedly
• never send the key to analytics as an event value
• never print the full key in release logs

The SDK verifies the key against the application identity and signed license response. Possessing the text value alone should not authorize an unrelated application.

Example build configuration

Android

Expose the key through a build configuration field:

android {
    defaultConfig {
        buildConfigField(
            "String",
            "NOSMAI_LICENSE_KEY",
            "\"${project.findProperty("NOSMAI_LICENSE_KEY") ?: ""}\""
        )
    }
}

Use it at startup:

NosmaiSDK.initialize(
    getApplicationContext(),
    BuildConfig.NOSMAI_LICENSE_KEY
);

Do not commit the local property containing the real production value.

iOS

Use an .xcconfig value:

NOSMAI_LICENSE_KEY = NOSMAI-YOUR-LICENSE-KEY

Map it into Info.plist through a build setting and read it at startup. Keep the real secrets file outside public source control.

Flutter

Use a compile-time environment value:

flutter run \
  --dart-define=NOSMAI_LICENSE_KEY=NOSMAI-YOUR-LICENSE-KEY

Read and validate it:

const licenseKey = String.fromEnvironment('NOSMAI_LICENSE_KEY');

if (licenseKey.isEmpty) {
  throw StateError('NOSMAI_LICENSE_KEY is missing');
}

final initialized = await NosmaiFlutter.initialize(licenseKey);

Build automation must supply the correct key for the selected environment.

Handle initialization failure

Do not continue into the camera experience as though initialization succeeded.

A production application should:

1. stop the loading state
2. record the technical error without the full key
3. distinguish a connection problem from a rejected license where possible
4. show a retry action for temporary failures
5. prevent paid or licensed features from being used without authorization
6. send the user back to a safe screen if the camera experience cannot start

Retry behavior

Retry after:

• network connectivity returns
• a temporary DNS failure
• a timeout
• the application returns to the foreground after a failed startup

Do not retry continuously in a tight loop. Use a user action or a limited delay between attempts.

On iOS, NosmaiCore provides license status and retry methods. Flutter and Android should use their platform status callbacks or initialize again only through the application's single SDK owner.

Changing the active key

Do not switch keys while the SDK is actively processing camera frames.

For a real environment change:

1. stop camera capture
2. stop recording or streaming
3. detach the preview
4. clean up the SDK
5. initialize again with the new key

Normal screen navigation does not require changing or reinitializing the key.

Production checklist

Before release, confirm:

• the production package name or bundle identifier matches the console project
• the production key is supplied by release automation
• the test key is not present in the release build
• the app has a clear initialization failure state
• temporary connection failures can be retried
• full keys are not written to logs
• the first-launch network requirement is covered by testing
• offline behavior is tested after a successful online verification
• the project includes every feature used by the application

For product information and account access, visit nosmai.com and the Nosmai Console.