iOS SDK for the SVRF API and ARKIt Face Filters
Branch: master
Clone or download
AndreiEvstratenko and RomanFrom710 Set new version in the podspec file (1.0.3) (#28)
* update version

* update dependency version
Latest commit 15a9694 Feb 19, 2019

README.md

The SVRF SDK

CocoaPods iOS Version Swift Version

SVRF allows you to supercharge your app with the first and largest search engine for immersive experiences. We make it simple for any developer to incorporate highly immersive experiences with all kinds of applications: virtual reality, augmented reality, mixed reality, mobile, and web.

The SvrfSDK is a framework for easy integration of the SVRF API and allows you to stream ARKit compatible 3D face filters into your application.

Requirements

  • iOS 11.0+
  • 3D Face Filters require an iPhone X or newer

Access and API Keys

To generate a SVRF API Key, create an account on www.svrf.com and go to the Apps section of the User Settings page.

See our terms of service for restrictions on using the SVRF API, libraries, and SDKs.

If you have questions or need support, please create a ticket in the svrf-api GitHub repository.

Attribution

SVRF requires developers to provide attribution. Please read our documentation and terms of service to learn about attribution requirements.

Rate Limits

The SVRF API has a generous rate limit. Please read our documentation to learn about API rate limits.

Installation

CocoaPods

1. Install CocoaPods

CocoaPods is a dependency manager for Cocoa projects. Enter the following command to install CocoaPods:

sudo gem install cocoapods

The process may take a long time, please wait. For further installation instructions, please check this guide.

2. Add the SvrfSDK entry to your Podfile

Add the SvrfSDK entry to your Podfile:

target :YourTargetName do
  pod 'SvrfSDK'
end

3. Install the SvrfSDK in the project

To install the SvrfSDK into your Xcode project, run the following command:

pod install

Note: If you saw "Unable to satisfy the following requirements" issue during pod install, please run the following commands to update your pod repo and install the pod again:

pod repo update
pod install

Manually

If you prefer not to use dependency manager, you can integrate the SvrfSDK into your project manually.

Examples

ARKitFaceFilterDemo - An example of the SvrfSDK in Swift.

Authentication

Configure your plist with your SVRF_API_KEY.

<plist version="1.0">
  <dict>
    <key>SVRF_API_KEY</key>
    <string>{your-api-key}</string>
  </dict>
</plist>

To authenticate the SvrfSDK, add the following to your didFinishLaunchingWithOptions function in AppDelegate:

SvrfSDK.authenticate()

Endpoints

Search Endpoint

The SVRF Search Endpoint brings the power of immersive search found on SVRF.com to your app or project. Our search engine enables your users to instantly find the immersive experience they're seeking. Content is sorted by the SVRF rating system, ensuring that the highest quality content and most relevant search results are returned first.

Parameter Type
query String
searchOptions SearchOptions
onSuccess (_ mediaArray: [Media]) -> Void
onFailure ((_ error: SvrfError) -> Void)?

Returns: [Media]?

Example

Search "Five Eyes" face filter; limited by "_3d" type and "Face Filters" category.

let searchOptions = SearchOptions(type: [._3d], stereoscopicType: nil, category: nil, size: nil, pageNum: nil)

SvrfSDK.search(query: "Five Eyes", options: searchOptions, onSuccess: { mediaArray in
    if !mediaArray.isEmpty {
        // Do what you want with the Media[]
        self.searchCollectionView.setupWith(mediaArray: mediaArray)
        self.searchCollectionView.reloadData()
    } else {
        let alertController = UIAlertController(title: "Empty Array", message: "No results found...", preferredStyle: .alert)
        alertController.addAction(UIAlertAction(title: "OK", style: .default))
        self.present(alertController, animated: true)
    }
}) { error in
    print("\(error.title). \(error.description ?? "")")
}

Trending Endpoint

The SVRF Trending Endpoint provides your app or project with the hottest immersive content - curated by real humans. The experiences returned mirror the SVRF homepage, from timely cultural content to trending pop-culture references. The trending experiences are updated regularly to ensure users always get fresh updates of immersive content.

Parameter Type
trendingOptions TrendingOptions
onSuccess (_ mediaArray: [Media]) -> Void
onFailure ((_ error: SvrfError) -> Void)?

Returns: [Media]?

Example

Get trending Media; limited by "video" type.

let trendingOptions = TrendingOptions(type: [.video], stereoscopicType: nil, category: nil, size: nil, nextPageCursor: nil)

SvrfSDK.getTrending(options: trendingOptions, onSuccess: { mediaArray in
    if !mediaArray.isEmpty {
        // Do what you want with the Media[]
        self.searchCollectionView.setupWith(mediaArray: mediaArray)
        self.searchCollectionView.reloadData()
    } else {
        let alertController = UIAlertController(title: "Empty Array", message: "No results found...", preferredStyle: .alert)
        alertController.addAction(UIAlertAction(title: "OK", style: .default))
        self.present(alertController, animated: true)
    }
}) { error in
    print("\(error.title). \(error.description ?? "")")
}

Media by ID Endpoint

Fetch Media by ID.

Parameter Type
id String
onSuccess (_ media: Media) -> Void
onFailure ((_ error: SvrfError) -> Void)?

Returns: Media?

Example

Get Media with ID "547963".

SvrfSDK.getMedia(id: "547963", onSuccess: { media in
    //Do what you want with the Media
    self.mediaTitleLabel.text = media.title ?? "unknown"
}) { error in
    print("\(error.title). \(error.description ?? "")")
}

Utilities

getNodeFromMedia

Generates a SCNNode for a Media with a type "3d". This method can used to generate the whole 3D model, but is not recommended for face filters. Face filters should be retrieved using the getFaceFilter method.

Parameter Type
media Media
onSuccess (_ node: SCNNode) -> Void
onFailure ((_ error: SvrfError) -> Void)?

Returns: SCNNode?

Example

Get SCNNode from Media with ID "547963".

SvrfSDK.getMedia(id: "547963", onSuccess: { media in
    SvrfSDK.getNodeFromMedia(media: media, onSuccess: { node in
        // Do what you want with the SCNNode
    }, onFailure: { error in
        print("\(error.title). \(error.description ?? "")")
    })
}) { error in
    print("\(error.title). \(error.description ?? "")")
}

getFaceFilter

The SVRF API allows you to access all of SVRF's ARKit compatible face filters and stream them directly to your app. Use the getFaceFilter method to stream a face filter to your app and convert it into a SCNNode in runtime. You can then attach the face filter to a SCNScene

Parameter Type
media Media
onSuccess (_ faceFilter: SCNNode) -> Void
onFailure ((_ error: SvrfError) -> Void)?

Returns: SCNNode

Example

Get a face filter SCNNode for Media with ID "547963".

SvrfSDK.getMedia(id: "547963", onSuccess: { media in
    SvrfSDK.getFaceFilter(with: media, onSuccess: { faceFilter in
        // Do what you want with the face filter
    }, onFailure: { error in
        print("\(error.title). \(error.description ?? "")")
    })
}) { error in
    print("\(error.title). \(error.description ?? "")")
}

setBlendShapes

Blend shape mapping allows SVRF's ARKit compatible face filters to have animations that are activated by your user's facial expressions.

Parameter Type
blendShapes [ARFaceAnchor.BlendShapeLocation : NSNumber]
node SCNNode

Example

Map blend shapes to a SCNNode's morpher.

class FaceFilter: SCNNode, VirtualFaceContent {

    var blendShapes: [ARFaceAnchor.BlendShapeLocation: NSNumber] = [:] {
        didSet {
            // Enumerate through all child nodes to find all morpher targets
            self.enumerateHierarchy({ (node, _) in
                if (node.morpher?.targets != nil) {
                    SvrfSDK.setBlendShapes(blendShapes: blendShapes, for: node)
                }
            })
        }
    }

    // VirtualFaceContent protocol's function
    func update(withFaceAnchor faceAnchor: ARFaceAnchor) {
        blendShapes = faceAnchor.blendShapes
    }
}

Errors

Errors are returned in a custom SvrfError. It includes a title and description to provide you with detailed information for the error you are encountering.

print(svrfError.title)
print(svrfError.description)