TjekSDK

Questions related to the SDK? Email us at [email protected].

Introduction

This is an SDK for interacting with the different Tjek services from within your own apps. The SDK has been split into several libraries, which can be loaded independently if you wish:

• TjekPublicationViewer: Includes several UIViewControllers for fetching, rendering, and interacting with, digital publications. These can be in PDF or Incito formats.
• TjekAPI: Makes sending requests to our API simple and type-safe. Contains all the model objects, and a number of specific requests, needed for interacting with our API.

For your convenience, these libraries are wrapped by the TjekSDK library. This is a simple wrapper around all the other libraries, allowing you to easily import and initialize them all.

Compatibility

Installation

TjekSDK supports the following dependency managers. Choose your preferred method to see the instructions:

.package(url: "https://github.com/tjek/tjek-swift-sdk.git", .upToNextMajor(from: "5.0.0"))

pod 'TjekSDK', '5.0.0'

pod 'TjekSDK/API', '5.0.0'

Getting Started

In order to use our SDK you will need to sign up for a free developer account.

This will give you an API key and a Track ID. The SDK must be initialized with these values in order to work.

Initialization via Config file

The easiest way to initialize the SDK is to simply save these 3 keys in a config file.

The file is called TjekSDK-Config.plist, and must be copied into your app's main bundle.

You can see an example of this file in the Examples project (located at ./Examples/SharedSource/TjekSDK-Config.plist)

Then, when your app starts, you just need to import the SDK and call initialize:

import TjekSDK

do {
    // Initialize the TjekSDK using the `TjekSDK-Config.plist` file.
    try TjekSDK.initialize()
} catch {
    print("❌ Unable to initialize TjekSDK", error.localizedDescription)
}

Initialize manually

If you would rather initialize the SDK programmatically, you can do so in code instead:

import TjekSDK

do {
    // Initialize the TjekSDK manually
    TjekSDK.initialize(
        config: try .init(
            apiKey: "<your api key>",
            trackId: .init(rawValue: "<your track id>")
        )
    )
} catch {
    print("❌ Unable to initialize TjekSDK", error.localizedDescription)
}

Examples

Open TjekSDK.xcworkspace to build and explore the different demo projects.

There is a demo for each dependency manager type (SPMDemo & CocoapodsDemo). Check their individual Readme files for more details.

Usage

PublicationViewer

There are two different ways of showing publications - as an Incito (vertically scrolling dynamic content) or as a PDF (horizontally paged static images).

You choose which one to use based on the hasIncitoPublication and hasPagedPublication properties on the Publication_v2 model - you can fetch this model using one of the publication requests in TjekAPI/CommonRequests.swift.

Incito Viewer

In order to show an Incito publication, you subclass IncitoLoaderViewController and call one of the super.load() functions. See Examples/SharedSource/DemoIncitoPublicationViewController.swift for more details.

PDF Viewer

To show a PDF publication, add an instance of PagedPublicationView to your view controller, and then call reload() on this view. See Examples/SharedSource/DemoPagedPublicationViewController.swift for more details.

TjekAPI

Once initialized (using TjekSDK.initialize, or TjekAPI.initialize), you will be able to use TjekSDK.api to access an instance of the TjekAPI class.

Note: you can also use TjekAPI.shared if you are only importing the TjekAPI library - TjekSDK.api is simply a reference to the TjekAPI.shared singleton.

It is via this TjekAPI class that you send APIRequests to our server.

An APIRequest is a struct that contains all the knowledge about how and where to send a server request, and how to parse the input and output data. We provide implementations of a number of our api requests.

The common pattern is to use a static function on the APIRequest type to generate the request object. You can also build APIRequests yourself, though this shouldnt be necessary.

Once you have a request object, you 'send' it to the API.

let request: APIRequest = .getPublication(withId: "<publication id>")
TjekSDK.api.send(request) { result in
	switch result {
	case let .success(publication):
		// `publication` is a concrete Publication type, as defined in the APIRequest
	case let .failure(error):
		// `error` is of type APIError
	}
}

The send function takes an APIRequest, and has a completion handler that is called (on main queue by default). Once completed you recieve a result Result<ResponseType, APIError> which contains either the success type (defined by the APIRequest) or an APIError.

We also provide an implementation of send that returns a Future - a promise of work to be done, which can be run at a later date. Details about using these Future types can be found here.

Changelog

For a history of changes to the SDK, see the CHANGES file.

This also includes migration steps, where necessary.

License

The TjekSDK is released under the MIT license. See LICENSE for details.