VGS Show iOS SDK

VGS Show is a product that lets you securely reveal previously tokenized/aliased data (text, images, PDFs) from Very Good Security (VGS) without that raw data ever passing through or being stored in your systems. VGSShowSDK decodes reveal responses and renders values directly into managed UI elements (VGSLabel, VGSImageView, VGSPDFView) while enforcing strict logging and masking rules.

Table of contents

• Before you start
• Integration
  • CocoaPods
  • Swift Package Manager
  • Toolchain Compatibility
• AI Agent Integration
• Usage
  • Import SDK
  • Create VGSShow instance and UI Elements
  • Reveal Request
  • Security & Logging
  • UI Components Overview
  • Testing Basics
  • Demo Application
  • Releases
  • Metrics
• Dependencies
• License

Before you start

1. Register or log in to your VGS Dashboard.
2. A sandbox vault is pre-created; use its Vault ID in initialization.
3. Ensure you already have aliases (e.g. created via VGS Collect) to reveal. To create aliases you can use VGSCollectSDK or follow the inbound connection guide in our docs.

Integration

CocoaPods

Add to your Podfile (pin exact version for reproducibility):

pod 'VGSShowSDK', '1.3.1'

Then run:

pod install

Swift Package Manager

From Xcode: File > Add Packages… and enter:

https://github.com/verygoodsecurity/vgs-show-ios

Select version rule “Exact” and specify 1.3.1.

Or in Package.swift (exact version pin):

// ...existing code...
dependencies: [
  .package(url: "https://github.com/verygoodsecurity/vgs-show-ios", exact: "1.3.1")
]
// ...existing code...

Toolchain Compatibility

VGSShowSDK supports Swift 5.9 and Swift 6 language modes. The SDK project is configured for Swift 6, while the Swift Package manifest intentionally remains // swift-tools-version:5.9 so SwiftPM clients using older compatible toolchains can still load the package.

CocoaPods publishes both supported Swift language versions through spec.swift_versions = ['5.9', '6.0'].

AI Agent Integration

This repository ships a public AI skill at skills/vgs-show-ios-guide/SKILL.md for teams integrating VGSShowSDK into an app.

Recommended: install the skill with skills.sh. This is the easiest way to give a compatible AI agent the repository-specific guidance it needs for VGSShowSDK integrations.

The installed skill bundle includes references/AGENTS.md, which is the canonical durable integration guide for this SDK.

What the skill is useful for:

• matching guidance to the installed VGSShowSDK version when that version can be detected
• steering integrations toward the correct reveal setup for text, image, PDF, and SwiftUI representable use cases
• enforcing non-empty contentPath values before requests and batching subscribed views through a single VGSShow
• preserving secure masking, safe copy behavior, and redacted error or logging guidance
• following the testing and upgrade rules in references/AGENTS.md

Install the skill with skills.sh:

npx skills add https://github.com/verygoodsecurity/vgs-show-ios --skill vgs-show-ios-guide

If your AI tool does not support skills yet, load skills/vgs-show-ios-guide/references/AGENTS.md directly.

Minimal System Prompt Example:

You are an autonomous engineering agent integrating the VGS Show iOS SDK into an existing Swift app.
Use skills/vgs-show-ios-guide/references/AGENTS.md as the authoritative policy.
Constraints:
- Only public, non-deprecated APIs.
- No raw sensitive data in logs/tests.
- All subscribed views must have non-empty contentPath values before requests.
- Secure masking applied before user-visible refresh when required.
Goals:
1. Add a screen revealing a user's details (card label, name label) using a single batched request.
2. Implement partial masking for the card.
3. Provide unit tests for missing path.
Return: Modified Swift source files only, no secrets.

Developer Prompt (Inline Example for a Single Task):

Task: Add secure display of account number with custom last-4 masking while preserving transformation regex formatting.
Follow skills/vgs-show-ios-guide/references/AGENTS.md.
Do not log raw account number; add tests for masking and a negative near-miss path key.

Usage

Import SDK

import VGSShowSDK

Create VGSShow instance and UI Elements

Use your `` to initialize a VGSShow instance for the desired environment (e.g. .sandbox).

/// VGSShow instance configured for sandbox.
let vgsShow = VGSShow(id: "", environment: .sandbox)

/// Labels for card data.
private let cardNumberLabel = VGSLabel()
private let expDateLabel = VGSLabel()

override func viewDidLoad() {
  super.viewDidLoad()

  // Set content paths (JSON keys expected in reveal response).
  cardNumberLabel.contentPath = "cardData.cardNumber"
  expDateLabel.contentPath = "cardData.expDate"

  // Subscribe views.
  vgsShow.subscribe(cardNumberLabel)
  vgsShow.subscribe(expDateLabel)

  // Configure appearance.
  configureUI()
}

private func configureUI() {
  let paddings = UIEdgeInsets(top: 8, left: 8, bottom: 8, right: 8)
  let font = UIFont.systemFont(ofSize: 20)
  let bg = UIColor.systemBlue

  [cardNumberLabel, expDateLabel].forEach { label in
    label.paddings = paddings
    label.font = font
    label.textColor = .white
    label.backgroundColor = bg
    label.layer.cornerRadius = 0
  }
  expDateLabel.characterSpacing = 0.83
}

Reveal Request

Perform a reveal request; matching JSON fields populate subscribed views automatically.

func revealData() {
  // Custom non-sensitive headers.
  vgsShow.customHeaders = [
    "X-USER-ID": UUID().uuidString
  ]

  // Additional payload keys as required by your backend contract.
  let customPayload = [
    "reveal": ["cardData.cardNumber", "cardData.expDate"]
  ]

  vgsShow.request(path: "/reveal", method: .post, payload: customPayload) { result in
    switch result {
    case .success(let statusCode):
      // Views already updated.
      print("Reveal success status=\(statusCode)")
    case .failure(let statusCode, let error):
      // Map error to safe user message (do not expose internals).
      let message = userMessage(for: error)
      print("Reveal failed status=\(statusCode), userMessage=\(message)")
    }
  }
}

private func userMessage(for error: Error?) -> String {
  guard let e = error as? VGSShowError, let type = e.type else { return "Reveal failed" }
  switch type {
  case .fieldNotFound: return "Requested data unavailable"
  case .invalidImageData, .invalidPDFData: return "Cannot display document"
  case .invalidBase64Data: return "Corrupted data"
  default: return "Reveal failed"
  }
}

UI Components Overview

• VGSLabel: Reveals text; supports secure masking (isSecureText + range methods), placeholder styling (VGSPlaceholderLabelStyle), transformation regex, clipboard copy (copyTextToClipboard).
• VGSImageView: Reveals base64 or raw image data; delegate reports success/failure; clear() removes current image.
• VGSPDFView: Reveals base64 PDF data; display customization (mode, direction, scaling); delegate error handling.

All components require a non-empty contentPath set before a request.

Demo Application

A demo application showcasing reveal flows is available: VGSShowDemoApp. Open VGSShowDemoApp/VGSShowDemoApp.xcodeproj and let Xcode resolve Swift package dependencies for the demo app.

Releases

Follow SDK updates on the Releases page.

Metrics

VGSShowSDK collects anonymous usage metrics (feature usage, version) to improve the product. No sensitive data is collected. Opt-out:

VGSAnalyticsClient.shared.shouldCollectAnalytics = false

Dependencies

• iOS 13+
• Swift 5.9 or Swift 6 language mode
• SwiftPM manifest tools version 5.9

License

VGSShow iOS SDK is released under the MIT license. See LICENSE for details.