Overview

KlugKeychain stores small values, such as flags, tokens or IDs, in the keychain of iOS and macOS. Unlike normal app storage, the keychain keeps these values when the app is uninstalled and installed again.

That makes it a durable anchor for things an app needs to remember across reinstalls, for example whether a device has already used a free trial, or whether an account was deleted before.

KlugKeychain is in daily use in the PetCam App, our proof of concept.

Features

Store, read, check and remove values by key
Values survive uninstalling and reinstalling the app
Encrypted by the operating system in the system keychain
One API for iOS and macOS
Simple synchronous calls, no events to handle

Supported platforms

iOS arm64

macOS Apple silicon · Intel

On other platforms isSupported returns false, so the same code can stay in a cross-platform app.

On Android, KlugDeviceId provides the same reinstall-proof anchor: the Android device ID stays the same after the app is uninstalled and installed again.

Getting started

Add the extension to your application descriptor:

app.xml

<extensions>
    <extensionID>com.klug.keychain.Keychain</extensionID>
</extensions>

On macOS the app must be signed with a keychain access group entitlement. On iOS no extra entitlement is needed.

Quick example

Trial.as

import com.klug.keychain.Keychain;

var keychain:Keychain = Keychain.getInstance();
if ( keychain.isSupported )
{
    if ( keychain.has( "trialUsed" ) )
        showPurchaseScreen();
    else
        keychain.set( "trialUsed", "true" );   // kept after a reinstall
}

API overview

Keychain.getInstance()	Returns the single instance.
isSupported	True on iOS and macOS.
set(key, value)	Stores a value, replacing an existing one. Returns true on success.
get(key)	Returns the stored value, or an empty string if there is none.
has(key)	True if a value is stored for the key.
remove(key)	Removes the value. Returns true once the key no longer exists.

Requirements

AIR SDK	51.x (HARMAN)
iOS	iOS 17 or later
macOS	macOS 11 or later
Signing (macOS)	Keychain access group entitlement