Opacity - Never miss the cache again.

This section describes how to integrate the Opacity iOS library into your iOS project using either CocoaPods or Swift Package Manager (SPM).

Requirements

Minimum Deployment Target: iOS 14.0 or higher
Xcode 12 or higher

Integration

Xcode has two common dependency-management engines: Swift Package Manager (SPM) and CocoaPods.

Swift Package Manager

To integrate the Opacity SDK using Swift Package Manager in Xcode, follow these steps:

Open your Xcode project.
Go to the menu bar, click File > Add Package Dependencies.
In the dialog that appears, paste the URL below into the top-right search field and click Add Package.
```
https://github.com/OpacityLabs/opacity-ios
```
Select the target (usually your main application) and click Add Package.

CocoaPods

Close Xcode.
Edit your Podfile. If you don't have one, see the CocoaPods directions.
In the top level target, add this line:
```
pod 'OpacityCore'
```
Install the pod (and any other required pods).
```
pod install
```
Using CocoaPods requires the script sandbox to be disabled. We do that in Xcode. To start Xcode, use this command to open the workspace.
```
open *.xcworkspace
```
Open your project, and set Build Settings > Build Options > User Script Sandboxing to No.

Using the Opacity SDK

After integrating the library, you can start using the Opacity functionality in your project.

The name you use to import the Opacity SDK depends on the package manager you used.

SPM
```
import OpacityCoreSwift
```
CocoaPods
```
import OpacityCore
```

To initialize the Opacity SDK, use the following code in the init() function.

   try? OpacitySwiftWrapper.initialize(
      apiKey: "<your API key goes here>",
      dryRun: false,
      environment: .Production,
      shouldShowErrorsInWebView: true
   )

The syntax to use an Opacity query is:

try? result = await OpacitySwiftWrapper.get("<the resource you query>", params:[:])

For example, to get a GitHub profile, you use OpacitySwiftWrapper.get("flow:github:profile", params:[:]).

Complete example

This is a complete running example you can use.

import SwiftUI

import OpacityCoreSwift

struct ContentView: View {

    @State var message: String = ""
    @State var buttonMessage: String = "Use Opacity"

    init() {
        try? OpacitySwiftWrapper.initialize(
            apiKey: "<Your API key goes here>",
            dryRun: false,
            environment: .Production,
            shouldShowErrorsInWebView: true
        )
    }

    var body: some View {
        VStack {
            Button(action: {
                Task {
                    if message == "" {
                        message = "Please wait"
                        var result: [String: Any] = [:]
                        try? result = await OpacitySwiftWrapper.get(name: "flow:github:profile", params:[:])
                        let jsonData = try JSONSerialization.data(withJSONObject: result, options: .prettyPrinted)
                        message = String(data: jsonData, encoding: .utf8)!
                        buttonMessage = "Clear"
                    } else {
                        message = ""
                        buttonMessage = "Use Opacity"
                    }
                }
            }) {
                Text(buttonMessage)
                    .font(.title)
                    .padding()
                    .background(Color.blue)
                    .foregroundColor(Color.yellow)
            }
            Text(message)
        }
    }
}

Using the example

Create a new project in Xcode.
Select the App Playground template and name your application.
Add the Swift library as explained above.
Replace ContentView with the code above.
On line 12 enter your own API key.
Wait until the app preview opens and click Use Opacity.
Wait until the GitHub logon page open, and log on to GitHub.
Wait until you see your profile in JSON format.

Detailed explanation

import SwiftUI

import OpacityCoreSwift

Import the libraries we need.

struct ContentView: View {

Define the top level view of the application.

    @State var message: String = ""
    @State var buttonMessage: String = "Use Opacity"

State variables.

    init() {
        try? OpacitySwiftWrapper.initialize(
            apiKey: "<your API goes here>",
            dryRun: false,
            environment: .Production,
            shouldShowErrorsInWebView: true
        )
    }

The init() function is called when the view is initialized. Here it initializes the Opacity SDK.

    var body: some View {

This is the actual view.

        VStack {

Create a vertical stack

            Button(action: {

The first item in the stack is a button.

                Task {

Task opens a new execution thread.

                    if message == "" {
                        message = "Please wait"

If the message is currently empty, we want to use the Opacity SDK. We need the user to wait until it is finished.

                        var result: [String: Any] = [:]
                        try? result = await OpacitySwiftWrapper.get(name: "flow:github:profile", params:[:])

This is the reason we opened a separate thread. OpacitySwiftWrapper.get() is an asynchronous function, and we need to wait for it to return. We don't want to wait in the main thread.

                        let jsonData = try JSONSerialization.data(withJSONObject: result, options: .prettyPrinted)
                        message = String(data: jsonData, encoding: .utf8)!

This is a way to convert result into a String we can display easily.

                        buttonMessage = "Clear"

And the next time the user clicks the button, it will be to clear the information.

                    } else {
                        message = ""
                        buttonMessage = "Use Opacity"
                    }
                }
            }) {

If there is a message and the user clicks the button, reset the application.

                Text(buttonMessage)
                    .font(.title)
                    .padding()
                    .background(Color.blue)
                    .foregroundColor(Color.yellow)
            }

This is how we specify the text and formatting for the button.

            Text(message)
        }
    }
}

The second part of the stack is message, displayed as simple text.

Conclusion

You have now successfully integrated the Opacity Core SDK into your iOS project. You can begin utilizing the SDK's features by following the example code provided above.