sparkscan-net-ios

SparkScan .NET for iOS Skill

Critical: Do Not Trust Internal Knowledge

Your training data may contain outdated or incorrect Scandit SDK APIs. The SparkScan API changes between major SDK versions — button-visibility / color properties get renamed, removed, or restructured. The .NET binding also uses different naming conventions than the Swift / Obj-C native SDK (PascalCase, Enabled instead of isEnabled, TimeSpan instead of TimeInterval, etc.), and a few naming choices differ from the rest of the .NET API.

Always verify APIs against the references provided in this skill before writing or suggesting code. Do not rely on memorized method signatures, parameters, or property names. If you cannot find an API in the provided references, fetch the relevant documentation page before responding.

.NET-iOS-specific gotchas worth flagging:

• This skill targets the non-MAUI .NET for iOS workload (project <TargetFramework>net10.0-ios</TargetFramework>, no <UseMaui> flag). For MAUI apps, use the sparkscan-net-maui skill instead.
• SparkScan and SparkScanSettings use plain new constructors, not Create(...) factories. This is unusual compared to the rest of the .NET API (BarcodeCapture.Create(...), BarcodeCaptureSettings.Create(), DataCaptureView.Create(...)). The canonical pattern is var settings = new SparkScanSettings(); var sparkScan = new SparkScan(settings); — writing SparkScan.Create(...) or SparkScanSettings.Create() is a compile error. DataCaptureContext.ForLicenseKey(key) still uses the factory form (it lives in Core, not Spark).
• SparkScanView.Create(parent, context, sparkScan, settings) IS a factory (unlike SparkScan itself). On iOS the parent argument is just this.View — there is no coordinator-layout container (that's Android-only). The created view is added to parentView automatically; do not call this.View.AddSubview(sparkScanView) yourself.
• iOS lifecycle is sparkScanView.PrepareScanning() in ViewWillAppear and sparkScanView.StopScanning() in ViewWillDisappear. Do not use OnPause / OnResume here — those are the Android-only API. Calling them on iOS will not compile (the iOS binding does not surface them).
• Pick the UIViewController constructor that matches how the controller is instantiated, or the camera preview will never appear. The dotnet new ios template that ships with modern .NET-iOS is scene-based (no Main.storyboard, UIApplicationSceneManifest in Info.plist, SceneDelegate.WillConnect builds the window programmatically) — in that project shape, the VC must expose a parameterless public ViewController() : base() { } and SceneDelegate.WillConnect calls new ViewController(). Older Scandit samples are storyboard-based (UIMainStoryboardFile in Info.plist, customClass="ViewController" in the storyboard) — those need public ViewController(IntPtr handle) : base(handle) { } because storyboard inflation invokes that ctor with a real native handle. Never call new ViewController(IntPtr.Zero) to bridge the two: IntPtr.Zero is a null native handle, so the resulting managed wrapper has no underlying UIViewController; this.View never attaches to the window, SparkScanView.Create(parentView: this.View, …) lands on a detached view, and the app launches into a blank screen with no camera and no scans. See references/integration.md "Scene-based vs storyboard instantiation" for the full callout.
• NSCameraUsageDescription in Info.plist is mandatory. Without it the app crashes on first camera access. iOS shows the system permission dialog automatically when the camera starts — there is no separate runtime-request API for the camera.
• The .NET ISparkScanListener has only two methods: OnBarcodeScanned(SparkScan, SparkScanSession, IFrameData?) and OnSessionUpdated(SparkScan, SparkScanSession, IFrameData?). There are no OnObservationStarted / OnObservationStopped methods (the way IBarcodeCaptureListener has them).
• Prefer the event API (sparkScan.BarcodeScanned += handler) over the listener interface in idiomatic C# — that's what the official .NET iOS SparkScan sample uses. The event handler receives SparkScanEventArgs with Session, FrameData, and SparkScan.
• IFrameData and the image buffers must be Dispose()d on iOS. The official sample uses using var imageBuffer = args.FrameData?.ImageBuffers.LastOrDefault(); and using var frame = imageBuffer?.ToImage();. Failing to dispose causes a frozen / stuttering preview. The SparkScanEventArgs.FrameData itself is IFrameData?. If you do not need the frame, do not retain it.
• Symbology names are C# PascalCase: Symbology.Ean13Upca, Symbology.Ean8, Symbology.Code128, Symbology.InterleavedTwoOfFive, Symbology.Qr, Symbology.DataMatrix. They are not Swift dot-case (.ean13UPCA).
• The capture mode's enabled property is sparkScan.Enabled (not IsEnabled).
• CodeDuplicateFilter is TimeSpan — not TimeInterval (that is the Swift type). Use TimeSpan.FromMilliseconds(500), TimeSpan.FromSeconds(2.5), or TimeSpan.Zero. SparkScanSettings does not expose CodeDuplicate.DefaultDuplicateFilter / ReportDataAndSymbologyOnlyOnce sentinels — those live on BarcodeCaptureSettings, not on SparkScan. For SparkScan, set the TimeSpan directly.
• Feedback is delivered through ISparkScanFeedbackDelegate.GetFeedbackForBarcode(Barcode) and assigned with sparkScanView.Feedback = this (or any object that implements ISparkScanFeedbackDelegate). Returning null from the delegate falls back to the default success feedback.
  • Success feedback: new SparkScanBarcodeSuccessFeedback() (default), or pass (Color), (Color, Brush), or (Color, Brush, Feedback?).
  • Error feedback: new SparkScanBarcodeErrorFeedback(message: "...", resumeCapturingDelay: TimeSpan.FromSeconds(60)). The view shows the error message, the trigger button shows an error state, and scanning resumes after the delay.
• GetFeedbackForBarcode(Barcode) is invoked on a background thread. Build the feedback object eagerly (in SetupSparkScan / ViewDidLoad) and just return it.
• SparkScan.BarcodeScanned (and ISparkScanListener.OnBarcodeScanned) also run on a background thread. Dispatch any UI update via DispatchQueue.MainQueue.DispatchAsync(() => { … }).
• SDK 8.0+ requires explicit initialization in AppDelegate.FinishedLaunching. Call ScanditCaptureCore.Initialize() + ScanditBarcodeCapture.Initialize() before any Scandit code runs. Without this the SDK's DI container has no registrations and the first new SparkScan(...) / SparkScanView.Create(...) call crashes at launch. Not required on 6.x / 7.x. See references/integration.md for the canonical AppDelegate.cs template.
• The NuGet packages are Scandit.DataCapture.Core and Scandit.DataCapture.Barcode. No separate *.Maui packages here — those are only for MAUI projects. Do not guess the version from training data — fetch the latest stable from https://www.nuget.org/packages/Scandit.DataCapture.Barcode/ via WebFetch before pinning. Inventing a non-existent version (e.g. 8.13.0 when only 8.4.0 is published) causes dotnet restore to fail with Unable to find package Scandit.DataCapture.Core with version (>= …). See references/integration.md Step 0 for the full procedure.
• SparkScanView.HardwareTriggerSupported and SparkScanViewSettings.HardwareTriggerKeyCode are Android-only and not surfaced on dotnet.ios. Do not reference them in iOS code.
• SparkScanScanningModeDefault and SparkScanScanningModeTarget are constructed with new, both taking (SparkScanScanningBehavior, SparkScanPreviewBehavior). There is no parameterless constructor in the .NET binding; the Swift init() overloads (no args) are not surfaced on dotnet.ios.
• View state is exposed via SparkScanView.ViewStateChanged (event of EventHandler<SparkScanViewStateEventArgs>) — there is no UiListener property on the .NET binding. Use the events BarcodeCountButtonTapped, BarcodeFindButtonTapped, LabelCaptureButtonTapped, and ViewStateChanged instead.