# How to Integrate

## Getting Started with VGS Show iOS SDK

Before you start, you can also check `VGSShowSDK` [GitHub Page](https://github.com/verygoodsecurity/vgs-show-ios), download [Demo Application](https://github.com/verygoodsecurity/vgs-show-ios/tree/master/VGSShowDemoApp) or browse the [References](https://verygoodsecurity.github.io/vgs-show-ios/).

> Make sure that you check our [best practices](/vault/developer-tools/vgs-show/security-checklist.md) to ensure secure configurations.

## How to Integrate the SDK

### Quickstart from Dashboard

You should have your organization registered at the [VGS Dashboard](https://dashboard.verygoodsecurity.com/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](https://cocoapods.org) and [Swift Package Manager](https://swift.org/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](https://github.com/verygoodsecurity/vgs-show-ios/blob/main/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.<br>

**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](https://cocoapods.org). Go to Terminal and run the command:

```bash
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:

```bash
pod init
```

And then open the file up in Xcode for editing:

```bash
open -a Xcode Podfile
```

Add `VGSShowSDK` pod to `Podfile` inside your project folder:

```ruby
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`:

```bash
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:

```bash
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](https://developer.apple.com/documentation/xcode/adding_package_dependencies_to_your_app) for more details.

Don't forget to import the module:

```swift
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](/vault/developer-tools/vault-management/going-live.md#sandbox-vs-live) type.

```swift
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

```swift
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).

```swift
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.

```swift
expDateLabel.contentPath = "card_data.data.card_number"
```

### Handle updates in VGSLabel

Implement `VGSLabelDelegate` to track changes in VGSShow views.

```swift
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.

```swift
@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](/vault/developer-tools/vgs-collect.md) or check our [code snippets](/vault/http-proxy/inbound-connection.md#try-it-out).

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.

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

See also:

* [UI Components](/vault/developer-tools/vgs-show/ios-sdk/ui-components.md)
* [Data Revealing](/vault/developer-tools/vgs-show/ios-sdk/reveal-data.md)
* [VGSShowSDK API Documentation](https://verygoodsecurity.github.io/vgs-show-ios/)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.verygoodsecurity.com/vault/developer-tools/vgs-show/ios-sdk/integration.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.