This is an SDK for interacting with the different Tjek services from within your own apps.
Questions related to the SDK? Email us at services@tjek.com.
Tjek SDK is available through Maven Central:
implementation "com.tjek.sdk:android-sdk:x.y.z"
Snapshots of the development version are available in Sonatype's snapshots repository.
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.
The easiest way to initialize the SDK is to put the keys in the AndroidManifest.xml file:
<application>
...
<meta-data
android:name="com.tjek.sdk.api_key"
android:value="your_api_key"/>
<meta-data
android:name="com.tjek.sdk.application_track_id"
android:value="your_track_id"/>
<!-- Optionally, you can also add the correspondent keys for development phase.
These are used only when the build is DEBUG type.-->
<meta-data
android:name="com.tjek.sdk.develop.api_key"
android:value="your_develop_api_key"/>
<meta-data
android:name="com.tjek.sdk.develop.application_track_id"
android:value="your_develop_track_id"/>
...
</application>You can also set these keys at runtime, but you need to set them before performing any request with the SDK:
TjekSDK.setApiKey(String): this will set your api key.TjekSDK.setApplicationTrackId(String): this will set the application track id.
If you wish to try our demo app, just clone the project and run it. We've included an API key that will work straight out of the box. But the key only provides a limited amount of queries per day so don't use it in production.
The sdk uses the new java.time classes insead of the old and deprecated Date and Calendar.
You need to add the following to your app module's build.gradle file:
android {
compileOptions {
// Flag to enable support for the new language APIs (For AGP 4.1+)
coreLibraryDesugaringEnabled = true
sourceCompatibility JavaVersion.VERSION_1_8
targetCompatibility JavaVersion.VERSION_1_8
}
dependencies {
coreLibraryDesugaring("com.android.tools:desugar_jdk_libs:1.1.5")
}
Check the official guide to verify other constraint you may have in your app.
There are two different ways of showing publications: Incito (vertically scrolling dynamic content) or PDF (horizontally paged static images).
You can choose which one to use based on the hasIncitoPublication and hasPagedPublication properties on the PublicationV2 model; you can fetch this model using one of the publication requests available in TjekAPI.
In order to show an Incito publication, you need to use IncitoPublicationFragment. You can also add an IncitoEventListener to it to receive relevant events.
Take a look at the example IncitoPublicationActivity for more details.
In order to show a PDF publication, you need to use PagedPublicationFragment. You can also add different types of listeners to it to receive relevant events.
Take a look at the example PagedPublicationActivity for more details.
Both fragments can be created with a newInstance call. For each fragment type there are two variations of the call, depending on the parameters you have:
newInstance(Id, <type>PublicationConfiguration): use this if you only have thepublicationIdnewInstance(PublicationV2, <type>PublicationConfiguration): use this if you have the wholePublicationV2model already.
Depending on the type of fragment, you need to use IncitoPublicationConfiguration or PagedPublicationConfiguration. Take a look at the examples to see how they're used, IncitoPublicationActivity and PagedPublicationActivity.
Both type of fragments allow you to customize the loading screen and the error screen. To do that, you have to add a callback using setCustomScreenCallback(callback: LoaderAndErrorScreenCallback). If you don't provide it, the fragments will use the default error and loading views. Take a look at LoaderAndErrorScreen.kt file to see what you need to provide and how the default callbacks look like.
In the TjekAPI object you can find all the network requests that is possible to perform using the Tjek SDK (remember to call TjekSDK.setApiKey if you don't provide a key in the manifest before using any of these functions). All the functions are suspend fun and return a ResponseType that can be Success, carrying the expected data type in the data property, or Error that contains an optional code and an optional message.
Some api return a data type of PaginatedResponse, usually returned when you request some lists of data. In this object there is a results property containing the list of data you asked and a PageInfo object containing the info regarding the next run of the same call. If PageInfo.hasNextPage is true it means that there are more data that can be loaded and you can runt the same call passing PageInfo.lastCursor as value for PaginatedRequestV2.nextPage.
Here is an example: fetching a list of publications given a certain location.
val location = LocationQuery(Coordinate(55.6310771, 12.5771624))
var hasMoreToLoad = true
var pagination = PaginatedRequestV2.firstPage()
while(hasMoreToLoad) {
when (val res = TjekAPI.getPublications(nearLocation = location, pagination = pagination)) {
is ResponseType.Error -> println("Error")
is ResponseType.Success -> {
// do something with the data
println("from ${pagination.startCursor}")
println("publications: ${res.data.results.joinToString { it.branding.name.toString() }}")
// update the info in the pagination object
pagination = pagination.nextPage(res.data.pageInfo.lastCursor)
// see if there are more data we can ask
hasMoreToLoad = res.data.pageInfo.hasNextPage
}
}
}
The Tjek SDK is unaware of any location information and it won't store it in any way. It is the app's responsibility to get it somehow. Some api calls have an optional LocationQuery parameter where you can set a Coordinate(latitude, longitude) and an optional maxRadius (in meters) if you want to limit the results to a certain area around the given coordinates.
If you want your location info to be recorded also in the events sent by the Tjek SDK, you need to set it using TjekSDK.setEventsLocation(Location): we recommend to set it only if the location is coming from a GPS-sourced data. All the events generated after you set the location will carry that info.
For a history of changes to the SDK, see the changelog file.
This also includes migration steps if needed.
Copyright (C) 2022 Tjek
Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at
http://www.apache.org/licenses/LICENSE-2.0
Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.