Skip to content

Releases

v0.2.0

Choose a tag to compare

@inTouchSRL inTouchSRL released this 20 Nov 15:20

The Squiddy SDK 0.2.0 for iOS, as a Swift package: add https://github.com/squiddy-cloud/squiddy-swift in Xcode, or .package(url: "https://github.com/squiddy-cloud/squiddy-swift", from: "0.2.0") in a Package.swift. Android and JVM projects take the same version from Maven Central, cloud.squiddy:squiddy:0.2.0.

SquiddyCore.xcframework.zip is the SDK's Kotlin framework, which the package downloads (checksum 0694f0bf9159ee88807ec6a18e54d7aa868d28cbe04295c216f6039115314f69).

Added

  • On npm, for the browser. Web apps add npm install @squiddy-cloud/sdk and
    import { initialize } from "@squiddy-cloud/sdk": the SDK compiled with Kotlin/JS to a library of ES modules, with
    TypeScript declarations, for a bundler (Vite, webpack, esbuild) or a <script type="module">. Its one dependency is
    ws from 8.21.3, a dependency of Ktor that the browser never loads but that a bundler resolves. Node.js is not a
    supported runtime.
  • The browser target. A js target and a facade for JavaScript and TypeScript, cloud.squiddy.sdk.web:
    initialize(options) takes a plain object and returns a Squiddy with config, gate and strings (the same
    object while they do not change), string(key, fallback?), the listeners onConfig, onGate and onStrings (each
    returns the function that stops it), settled() (a Promise of the first state that is not pending),
    setLanguage, refresh and close. The states, gates and errors have a kind string, a closed set like their
    Kotlin classes. In a page the SDK calls Squiddy with fetch, through the data plane's CORS, names itself in
    X-User-Agent, sends app_type web, keeps its archive and installation id in localStorage (in memory where the
    browser refuses it), checks while the page is visible (document.visibilityState) and follows
    navigator.language. Its TypeScript declarations are dumped in squiddy/api/js/squiddy.d.mts. There is no push
    update in a page: a page cannot subscribe to a topic of Firebase Cloud Messaging, and it checks whenever it becomes
    visible.
  • Kotlin/JS on Maven Central. cloud.squiddy:squiddy-js, the klib of the js target: a Kotlin Multiplatform
    project with a js target takes it through cloud.squiddy:squiddy:0.2.0, and calls
    Squiddy.initialize(SquiddyOptions(...)), as on the other platforms.

Changed

  • The POM names the SDK's guide, https://docs.squiddy.cloud/sdk/, as the project's page, and the developer
    Squiddy with contact@squiddy.cloud and https://squiddy.cloud. The API of Android, the JVM and iOS does not change.

v0.1.0

Choose a tag to compare

@inTouchSRL inTouchSRL released this 19 Nov 01:29

The Squiddy SDK 0.1.0 for iOS, as a Swift package: add https://github.com/squiddy-cloud/squiddy-swift in Xcode, or .package(url: "https://github.com/squiddy-cloud/squiddy-swift", from: "0.1.0") in a Package.swift. Android and JVM projects take the same version from Maven Central, cloud.squiddy:squiddy:0.1.0.

SquiddyCore.xcframework.zip is the SDK's Kotlin framework, which the package downloads (checksum ad92e34d2250562c4dfe1ba7750181a9e2565ad1b62c3be19c2aa1eaba1e8e92).

The first version of the SDK: everything below is new.

Added

  • On Maven Central. Android and JVM projects add implementation("cloud.squiddy:squiddy:0.1.0"), and Gradle picks
    the artifact of the platform (squiddy-android, squiddy-jvm, and the iOS klibs for a Kotlin Multiplatform app).
    Every artifact comes with its sources and its API reference, and is signed.
  • One SDK for Android, the JVM and iOS. A Kotlin Multiplatform library under the Apache License 2.0, for Android
    API 24 and later (compiled against API 37, which OkHttp 5.5 requires of the apps too), Java 17 and later, and iOS 15
    and later on devices and on the simulators of Apple silicon and Intel Macs.
  • The data-plane contract of Squiddy. The SDK calls squiddy.v1.ConfigService/GetRemoteConfiguration with the
    Connect protocol in binary, over Ktor (OkHttp on Android and the JVM, NSURLSession on iOS). Its copy of
    config.proto is Squiddy's file byte for byte, and the protocol's messages stay inside the SDK.
  • The API key travels only in X-API-Key. It never appears in a log line, a URL or a toString. Every call names
    the SDK in its User-Agent (squiddy-kotlin/<version>), times out after 10 seconds by default and follows no
    redirect.
  • Initialization from the app's context. Squiddy.initialize takes SquiddyOptions (host, apiKey, appId,
    appVersion as YYYY.MM.DD, appMode, and optionally customParams, bundleId, language, entityId,
    timeout, refreshInterval, pushRefreshJitter, logger). It validates them and reads the rest from the
    platform: the app type (android, ios, desktop), the bundle id and the language. It reads and writes no file
    on the calling thread (see below).
  • The configuration as observable state. Squiddy.config is a StateFlow<SquiddyState>: Pending, then
    Ready with its ConfigurationOrigin (CACHE or NETWORK), or Failed with the error and the last valid
    configuration. RemoteConfiguration gives the version, the ServerApi block and its settings, whose
    asInt(), asDouble() and asBoolean() throw a SettingTypeException for a value of another type. refresh()
    asks for an update, and close() ends the instance.
  • Typed errors. SquiddyError has one case per failure of the data plane: Unauthenticated, AppNotPublished,
    InvalidRequest, IncompleteConfiguration, TenantSuspended, ServerError (with Squiddy's exceptionCode),
    RateLimited (with retryAfter), Network, Timeout and MalformedResponse.
  • Offline first. The last valid configuration is stored on the device and served before the network, also across
    launches. It is written atomically, and the API key is never stored. It lives in noBackupFilesDir on Android, in
    Application Support on iOS (kept out of backups), and in the app's directory of the system's data directory on
    the JVM: on macOS in Application Support, kept out of Time Machine with tmutil addexclusion, and on Windows in
    %LOCALAPPDATA%, which a roaming profile does not carry.
  • Gradual rollouts. Each installation gets an id of its own, a UUID sent as entity_id, so that a percentage
    rollout reaches a stable share of the installations. A backup restored onto another device, a Mac set up from a
    Time Machine backup or a roaming Windows profile does not carry it. An app can pass its own id instead
    (entityId).
  • Conditional requests. A call carries the fingerprints of the stored configuration and languages, so Squiddy
    answers not_modified or leaves out what did not change; the SDK merges the partial answer into the stored one.
    From a Squiddy that echoes lang_fingerprint with unchanged languages (release 20261118-39b4121 and later), an
    answer without languages and without the echo removes the stored languages: the configuration no longer has any for
    the app. The archive remembers whether its server has echoed, so the answers of an earlier server keep the
    languages as before.
  • The refresh policy. The SDK checks the configuration at every start, whenever the app comes back to the
    foreground, and every refreshInterval while it stays there (5 minutes by default, at least 30 seconds); never in
    the background. A check is a conditional call: an unchanged configuration costs a not_modified answer. The
    foreground comes from the activities on Android, from UIApplication's notifications on iOS, and is permanent on the
    JVM. After a failure it keeps serving the stored configuration and retries with an exponential backoff with jitter.
    It honours Retry-After after a 429, and after Unauthenticated it stops until refresh(). The README counts the
    installations in the foreground that a key of each plan holds.
  • Mandatory updates and maintenance. Squiddy.gate is a StateFlow<AppGate>: None, UpdateRequired or
    Maintenance, with the title and message Squiddy sends in the app's language, also from the stored configuration.
    The notices are readable as RemoteConfiguration.appUpdate and infoPoint.
  • Localized strings. Squiddy.string(key) and string(key, fallback) read the configuration's strings in the
    app's language, then in the default language, then the fallback; Squiddy.strings observes them. An empty string is
    a missing translation, as a cell left blank in the dashboard's translations grid: the lookup falls back and never
    returns an empty text. The titles of AppGate keep their meaning: empty when the configuration gives none.
  • The language follows the user and the app. Squiddy.setLanguage(language) (in Swift try setLanguage(_:),
    which throws SquiddyLanguageError) chooses the language of the requests, and null follows the user's again. The
    user's language is followed while the app runs: through the app's configuration changes on Android,
    NSCurrentLocaleDidChangeNotification on iOS, and at every check on the JVM. After a change the strings are read in
    the new language at once, and the SDK checks with Squiddy at once, in the foreground, so the texts of gate follow;
    the archive keeps the language each configuration was received in, and no call is made for a language it already has.
  • Push update. Squiddy can ask an app's installations to update now, with a data-only message of Firebase Cloud
    Messaging sent to the configuration's topic. The app subscribes to Squiddy.pushTopic and passes the data of the
    messages it receives to Squiddy.handlePush(data) (in Swift handlePush(_ userInfo:), in Java
    getPushTopic() and handlePush(Map)), which returns true for Squiddy's (squiddy = refresh) and checks the
    configuration after a random wait of up to pushRefreshJitter (60 seconds by default, zero allowed; in Java
    SquiddyOptionsBuilder.pushRefreshJitter(Duration)), in the background too. The wait respects Retry-After, the
    backoff and the stop after Unauthenticated, and a burst of notifications costs one call. The topic follows a rule
    Squiddy computes in the same way, from the key's SHA-256 and the app id (the README has it, with its test vectors),
    so each environment has its own topic. The SDK does not depend on Firebase; the README shows the wiring on Android
    and iOS.
  • Logging. A SquiddyLogger receives the SDK's DEBUG and WARNING lines, never the API key.
  • No disk access on the calling thread. initialize reads and writes no file on the thread that calls it, on every
    platform: the SDK finds and readies its directory and reads and writes its files on its own I/O threads, and
    config is Pending until the stored configuration is read. On Android it runs under a StrictMode thread policy
    that detects disk reads and writes without a violation, also when it asks for noBackupFilesDir. No member of an
    instance waits for the disk.
  • Android artifact. An AAR that asks only for INTERNET, publishes R8 consumer rules and declares no component or
    initializer of its own (OkHttp's androidx.startup initializer stays, and the README says how to remove it).
  • JVM artifact. A JAR of Java 17 class files.
  • A Java facade, on the JVM and on Android. Java builds the options with SquiddyOptionsBuilder, every option
    included, the timeout and the refresh interval as java.time.Duration (on Android below API 26 with core library
    desugaring, as any use of java.time), and creates an instance with a static call: SquiddyJvm.initialize(options)
    or SquiddyJvm.initialize(options, storageDirectory), and SquiddyAndroid.initialize(context, options). It follows
    config, gate and strings with addConfigListener, addGateListener and addStringsListener, which call a
    SquiddyListener on a background thread of the SDK and return a SquiddyObservation to cancel(), and reads the
    retryAfter of a RateLimited with SquiddyErrors.retryAfter(error). refresh(), setLanguage(...) and close()
    are plain Java. The listeners serve Kotlin without coroutines as well.
  • iOS artifact. SquiddyCore.xcframework, a dynamic framework with a device slice and a simulator slice for both
    kinds of Mac, under the Swift module Squiddy.
  • The Swift API. import Squiddy: try Squiddy.initialize(_:) with a SquiddyOptions struct whose durations are
    seconds; config, gate and strings with value, observe(_:) (on the main thread, cancellable, a Combine
    Cancellable) and values (an AsyncStream); `...
Read more