How to Integrate

Getting Started with VGS Show iOS SDK

Before you start, you can also check VGSShowSDK GitHub Page, download Demo Application or browse the References.

Make sure that you check our best practices to ensure secure configurations.

How to Integrate the SDK

Quickstart from Dashboard

You should have your organization registered at the VGS Dashboard. Sandbox vault will be pre-created for you. You should use your vault id to start reveal data. Follow integration guide below.

Integrate VGSShowSDK into Your iOS Project

Step 1: Install the SDK

VGSShowSDK is distributed through CocoaPods and Swift Package Manager.

AI Agent Integration & Assisted Development

To accelerate your integration and ensure your implementation follows VGS best practices, you can use the AGENTS.md file as a context for AI Coding Agents. Attach or reference the URL to the AGENTS.md file to your agent's context: https://github.com/verygoodsecurity/vgs-show-ios/blob/main/AGENTS.md.

Example System Prompt: "You are an autonomous engineering agent integrating the VGS Show iOS SDK into an existing Swift app. Use the contents of AGENTS.md as your authoritative policy.

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 the missing path.”

Integrate with CocoaPods

Install the latest version of CocoaPods. Go to Terminal and run the command:

sudo gem install cocoapods

If you don't have an existing Podfile in your project, go to your project folder and run the following command to create one:

pod init

And then open the file up in Xcode for editing:

open -a Xcode Podfile

Add VGSShowSDK pod to Podfile inside your project folder:

target 'MyApp' do
  use_frameworks!

  // Add VGSShowSDK pod here
  pod 'VGSShowSDK'

end

Back to your terminal window and run the following command to install VGSShowSDK:

pod install

Use the <your-app>.xcworkspace file to open your project in Xcode, instead of the .xcodeproj file, from here on out.

Update pods(optional)

If you installed VGSShowSDK before, you might need to update the SDK to the latest version. To do that run in terminal following command:

pod update

Integrate with Swift Package Manager

To use Swift Package Manager, in your Xcode project add the https://github.com/verygoodsecurity/vgs-show-ios.git repo. Follow the official Apple SPM Guide for more details.

Don't forget to import the module:

import VGSShowSDK

Next

Follow the integration guide to check the example how to create simple form for revealing credit cards data from your Vault.

Configure Your App

To initialize VGSShow you have to set your vault id and Environment type.

import UIKit
import VGSShowSDK

class ViewController: UIViewController {

    /// Create VGSShow instance with your VaultID.
    let vgsShow = VGSShow(id: "<VAULT_ID>", environment: .sandbox)

    // ...
}

Configure UI Components

Create UI Form

import UIKit
import VGSShowSDK

class ViewController: UIViewController {

    /// VGSShow instance.
    let vgsShow = VGSShow(id: "<VAULT_ID>", environment: .sandbox)

    /// VGSShow views.
    let cardNumberLabel = VGSLabel()
    let expDateLabel = VGSLabel()

    /// Native UI components.
    lazy var sendButton: UIButton = {
        let button = UIButton()
        button.translatesAutoresizingMaskIntoConstraints = false
        button.layer.cornerRadius = 4
        button.backgroundColor = .systemBlue
        button.setTitle("Reveal", for: .normal)
        button.setTitle("Loading", for: .disabled)
        button.setTitleColor(UIColor.white.withAlphaComponent(0.5), for: .disabled)
        button.addTarget(self, action: #selector(revealData), for: .touchUpInside)
        return button
    }()

    override func viewDidLoad() {
        super.viewDidLoad()

        // Setup basic layout.
        setupLayout()

        // Setup contentPath.
        setupContentPath()

        // Register VGSShow views in vgsShow instance.
        vgsShow.subscribe(cardNumberLabel)
        vgsShow.subscribe(expDateLabel)

        // Set delegates.
        cardNumberLabel.delegate = self
        expDateLabel.delegate = self

        // Configure UI.
        configureUI()
    }

    /// Create UI form for revealing data.
    func setupLayout() {
        let stackView = UIStackView.init(arrangedSubviews: [cardNumberLabel, expDateLabel, sendButton, copyButton])
        stackView.axis = .vertical
        stackView.spacing = 12
        stackView.distribution = .fillEqually
        stackView.translatesAutoresizingMaskIntoConstraints = false
        view.addSubview(stackView)
        NSLayoutConstraint.activate([
                stackView.leftAnchor.constraint(equalToSystemSpacingAfter: view.leftAnchor, multiplier: 2),
                view.rightAnchor.constraint(equalToSystemSpacingAfter: stackView.rightAnchor, multiplier: 2),
                stackView.topAnchor.constraint(equalTo: view.topAnchor, constant: 60),
                stackView.heightAnchor.constraint(equalToConstant: 200)
        ])
    }

    private func configureUI() {
        let paddings = UIEdgeInsets.init(top: 8, left: 8, bottom: 8, right: 8)
        let textColor = UIColor.darkText
        let borderColor = UIColor.blue
        let font = UIFont.systemFont(ofSize: 20)
        let backgroundColor = UIColor.white
        let cornerRadius: CGFloat = 0
        let placeholderColor = UIColor.darkText.withAlphaComponent(0.6)

        cardNumberLabel.textColor = textColor
        cardNumberLabel.paddings = paddings
        cardNumberLabel.borderColor = borderColor
        cardNumberLabel.font = font
        cardNumberLabel.backgroundColor = backgroundColor
        cardNumberLabel.layer.cornerRadius = cornerRadius

        cardNumberLabel.placeholder = "Card number"
		    cardNumberLabel.placeholderStyle.color = placeholderColor

        expDateLabel.textColor = textColor
        expDateLabel.paddings = paddings
        expDateLabel.borderColor = borderColor
        expDateLabel.font = font
        expDateLabel.backgroundColor = backgroundColor
        expDateLabel.layer.cornerRadius = cornerRadius
        expDateLabel.characterSpacing = 0.83

        expDateLabel.placeholder = "Expiration date"
		    expDateLabel.placeholderStyle.color = placeholderColor
   }

    private func setupContentPath() {}

    @objc func revealData() {}
}

Set content path

Set corresponding contentPath properties of VGSLabel instances. Each contentPath name should match key path in your reveal response object (JSON).

private func setupContentPath() {
    // Set corresponding content path to your VGSLabel.
    cardNumberLabel.contentPath = "<CONTENT_PATH_CARD_NUMBER>"
    expDateLabel.contentPath = "<CONTENT_PATH_EXP_DATE>"
}

• It is important to setup proper content path. - VGSShow cannot reveal data to subscribed views if content paths are not specified or set incorrectly.\

Use . to specify a multi-level nested content path.

expDateLabel.contentPath = "card_data.data.card_number"

Handle updates in VGSLabel

Implement VGSLabelDelegate to track changes in VGSShow views.

extension ViewController: VGSLabelDelegate {
// Track errors in labels.
func labelRevealDataDidFail(_ label: VGSLabel, error: VGSShowError) {
	print("error \(error) in label with \(label.contentPath)")
	label.borderColor = .red
}

// Track text changes in labels.
func labelTextDidChange(_ label: VGSLabel) {
	label.borderColor = .green
}

Request data

Use vgsShow.request(_:) to reveal data from subscribed VGS Show UI components. Update your app state in the request completion block.

@objc func revealData() {
    let payload = ["<CONTENT_PATH_CARD_NUMBER>" : "<REVEAL_ALIAS_1>",
                    "<CONTENT_PATH_EXP_DATE>"    : "<REVEAL_ALIAS_2>"]

    sendButton.isEnabled = false
    vgsShow.request(path: "<YOUR_PATH>",
                                    method: .post, payload: payload) { (requestResult) in

        // Update your UI with corresponing result.
        switch requestResult {
        case .success(let code):
            // Update UI for success state.
            self.sendButton.isEnabled = true
            print("vgsshow success, code: \(code)")
        case .failure(let code, let error):
            // Update UI for failed state.
            self.sendButton.isEnabled = true
            print("vgsshow failed, code: \(code), error: \(error)")
        }
    }
}

To create test aliases, you can use VGS Collect SDK or check our code snippets.

As a result you should receive a successful response and see the revealed data in VGSLabel.

Error handling

When VGSShow can not reveal data for some subscribed views, it will reveal and display partially decoded data. If the response doesn't contain the key specified in the subscribed view contentPath VGSLabel delegate method labelRevealDataDidFail(_:) will be called. Implement VGSLabelDelegate protocol and set VGSLabel delegate. You can use labelRevealDataDidFail func to handle reveal errors.

extension ViewController: VGSLabelDelegate {
    func labelRevealDataDidFail(_ label: VGSLabel, error: VGSShowError) {
        // Set label border to red color on error.
        label.borderColor = .red
    }
}

See also:

• UI Components

• Data Revealing

• VGSShowSDK API Documentation