SDK quick starts

What every SDK includes

• Rendering straight to native pixels, plus PNG, SVG and PDF export, and a view for the platform’s UI toolkit.
• A scanner for still images and camera frames. It finds the frame, fits it to each profile and decodes, trying Profile 0 first.
• Payload actions that follow the conventions: described, validated, and never performed automatically.
• Style checks and certification. The default strict policy refuses a style that might not scan and says why.
• Optional telemetry, anonymous aggregate scan counts that you can turn off in one line. See telemetry.

Swift: iOS and macOS

A Swift package for iOS 15 and macOS 12 or later. In Xcode, choose File, Add Package Dependencies, and enter the repository URL. The CKeyScanner product (import CKeyScanKit) is scanning only, with no renderer and no telemetry.

// https://github.com/clearkeysolutions/ckey
import CKey

CKey.telemetry = .off                                   // optional: opt out first

let symbol = try CKeySymbol.encode("https://openckey.org")   // smallest version that fits
let image: CGImage = try symbol.cgImage(size: 1024)          // black on white
let png: Data = try symbol.pngData(size: 1024, dpi: 300)

if let result = CKeyDecoder.decode(cgImage: image), let text = result.text {
    let action = CKeyPayload.classify(text)               // show it; act only on a tap
}

Swift SDK README

Web: WebAssembly

An ES module with the core compiled to WebAssembly, for browsers, workers and Node. ckey.wasm loads from next to ckey.mjs, or from wasmUrl. This site’s renderer and scanner use it.

npm install ckey

import { loadCKey } from "ckey";

const ckey = await loadCKey({ telemetry: 0 });   // 0 = telemetry off
const sym = ckey.encode("https://openckey.org", { level: "M" });
ckey.renderToCanvas(sym, document.querySelector("canvas"), { size: 512 });
const svg = ckey.renderSVG(sym);
sym.free();

const scanner = ckey.createScanner({
  onResult(result) {
    const action = ckey.classifyPayload(result.text ?? result.bytes);
    showResult(result, action);                    // never act automatically
  },
});
scanner.processFrame(context.getImageData(0, 0, canvas.width, canvas.height));

Web SDK README

Android: Kotlin

Maven artifacts org.openckey:ckey, with ckey-compose for a Compose image and ckey-camerax for a CameraX analyzer. Minimum SDK 24. The library declares no permissions.

dependencies {
    implementation("org.openckey:ckey:VERSION")
    implementation("org.openckey:ckey-camerax:VERSION")   // optional
}

CKey.telemetry = 0                                         // optional: opt out

val symbol = CKeySymbol.encode("https://openckey.org")
val bitmap = symbol.toBitmap(sizePx = 600)
val result = CKeyDecoder.decode(bitmap)                    // result?.action is never performed for you

Android SDK README

.NET

The NuGet package CKey targets net8.0 and netstandard2.0; CKey.Wpf adds WPF helpers. The namespace is OpenCKey.

dotnet add package CKey

using OpenCKey;

CKey.Telemetry = 0;                                        // optional: opt out

CKeySymbol symbol = CKeySymbol.Encode("https://openckey.org");
byte[] png = symbol.ToPng(1024);
byte[] pdf = symbol.ToPdf(widthPt: 144);                   // 2 inches wide, vector

.NET SDK README

C and C++

The core itself, behind the C interface in include/ckey/ckey.h. cmake --install provides a CMake package, split so an app links only what it needs: CKey::scan for a reader, CKey::core for everything.

find_package(CKey 0.1 REQUIRED)
target_link_libraries(app PRIVATE CKey::core)      # or CKey::scan for scanning only

#include <ckey/ckey.h>

ckey_telemetry_set_mode(0);                        // optional: opt out at run time

ckey_scalable_symbol symbol{}; ckey_diagnostics diag{};
const char *url = "https://openckey.org";
ckey_encode_scalable(reinterpret_cast<const uint8_t *>(url), std::strlen(url),
                     0, CKEY_ECC_M, CKEY_LAYOUT_STANDARD, &symbol, &diag);

Scanners can also leave telemetry out of the build entirely with -DCKEY_BUILD_TELEMETRY=OFF. C example

Command line

The ckey tool writes symbols as SVG, PNG and PDF, including print bitmaps at a physical size. It sends no telemetry.

brew install --formula ./ckey.rb
ckey encode-scalable --utf8 "https://openckey.org" --out code.svg
ckey encode-scalable --utf8 "https://openckey.org" --pdf code.pdf --size-in 2
ckey encode-scalable --utf8 "https://openckey.org" --layout print --png small.png --size-in 0.5 --dpi 600

Command-line source

Before you ship

• Follow the payload safety rules: show the payload and let the person tap.
• Decide on telemetry, and mention it in your own privacy disclosures if you leave it on.
• Verify downloaded packages against their SHA-256 and build attestation; the downloads page shows how.
• Test printed codes on the paper and at the size you will use them. See printing a CKey.