Integrating with your iOS app

App Embed

Integrating with your iOS app

The App Embed Component for iOS is a folder that is incorporated into your Xcode project. It provides a set of UIViewControllers that host the complete Zappar environment.

1. Unzip the App Embed Component

Copying the ZapparEmbed.include folder

The App Embed Component download is a zip file that contains:

ZapparEmbed.include
The embed component itself - this is what will be integrated into your app.
ZapparEmbedTest
An example Xcode project that demonstrates the integration.

The first step is to unzip the contents into a folder of your choosing.

2. Copy ZapparEmbed.include into your project directory

Don't worry that the directory is over 300 MB. This is because it contains bitcode – the compiled app will be much smaller!

3. Add ZapparEmbed.include to your project

Importing ZapparEmbed.include

To do this in Xcode:

  1. Right click on your project name in the Project navigator on the left of the screen
  2. Select “Add Files to...”
  3. Select ZapparEmbed.include
  4. Ensure that “Create groups for any added folders” is selected
  5. Press “Add”

4. Add API key to Info.plist

Adding an API key

Add an entry to the Info.plist file for your project.

Key
ZapparEmbedKey
Type
String
Value
your-api-key

Where your-api-key is the key we supplied you for this application. Note that the API key is tied to the bundle identifier of your app (e.g. com.example.myapp). If you change your bundle identifier you will have to request a new API key from us at support@zappar.com.

5. Modify your ViewController to start the Zappar component

Set Bridging Header

Because the Zappar framework uses Objective-C functions, you need to specify a bridging header; this header links your Swift project to the rest of the Zappar project as follows (for example, we’ve used SwiftEmbed-Bridging-Header.h for the “SwiftEmbed” project).

#import <ZapparEmbed/ZapparEmbed.h>
#import "TargetConditionals.h"

You need to specify this bridging header in the project settings as follows:

Project -> Build Settings -> Swift Compiler -General -> Objective-C Bridging Header

The Zappar embed functionality can be accessed through the viewController method in the ZapparEmbed framework. Here is an example of an action from a button that launches the embed component:

@IBAction func goZappar(_ sender: Any) {

   let zappar = ZapparEmbed.viewController(with: self)
   self.present(zappar!, animated: true, completion: nil)

}

Also, you will need to modify your ViewController to adopt the ZapparDelegate protocol as an extension to your ViewController class to provide the exit functionality for the Zappar component, e.g:

extension ViewController: ZapparDelegate {

    func zapparClose() {
        self.dismiss(animated: true)
    }
}

6. Add additional Info.plist entries

Add the following entries to your Info.plist file:

Privacy - Camera Usage Description
A string of your choice, e.g: "To provide augmented reality amazingness."
Privacy - Calendars Usage Description
A string of your choice, e.g: "To save this entry to your calendar."
Privacy - Contacts Usage Description
A string of your choice, e.g: "To save this entry to your contacts."
Privacy - Photo Library Usage Description
A string of your choice, e.g: "To save this snapshot into your camera roll."
Privacy - Photo Library Additions Usage Description
A string of your choice, e.g: "To save this snapshot into your camera roll."
Privacy - Microphone Usage Description
A string of your choice, e.g: "To allow sound to be recorded when using a Video Record function."

These entries are essential to ensure correct behavior of the embed component at runtime; if they are not set the app may crash due to insufficient permissions being permitted for a user. If they are set in the Info.plist, the user can still decline the app permission, but if the permissions are not included in the project, it will not work.

The following steps can often be required to finish the implementation of an embed:

  1. Add dependent Frameworks to project. Look through the troubleshooting guide if your project build fails to automatically link to Zappar’s required standard system frameworks.

  2. Check ObjC flag is set. In “Other Linker Flags”, add -ObjC to ensure the app will access the framework library functions safely.

Next Steps

With the component successfully launching in your app, you may wish to complete our Regression Test suite to ensure it works correctly in place.

The next article discusses the options for customizing the user interface of the Zappar component:

Open in new window