Skip to content

Connection ​

Skapi ​

kotlin
import com.skapi.Skapi

val skapi = Skapi(
    projectId: String,
    storage: SkapiStorage = MemoryStorage(),
    timeoutSeconds: Long = 120,
    targetCdn: String? = null,
    encryption: EncryptionOptions? = null,
)
java
import com.skapi.java.SkapiJava;

SkapiJava skapi = new SkapiJava(
    String projectId,
    SkapiStorage storage,          // default new MemoryStorage()
    long timeoutSeconds,           // default 120
    String targetCdn,              // default null
    EncryptionOptions encryption   // default null
);
// leave out arguments from the right: new SkapiJava("<Project ID>")
argument
projectIdthe Project ID from your project's Settings page on skapi.com
storagewhere the signed-in session is kept: MemoryStorage() (this object only), FileStorage(path) (a JSON file created readable by you only), skapi-android's SharedPreferencesStorage(context), or any SkapiStorage
timeoutSecondsseconds to wait for each request (connect, read and write)
targetCdnadvanced: the CDN host the SDK reads the project's endpoint list from. Leave it null.
encryptionEncryptionOptions(...): encrypts the data of private records on the device before upload. See Encryption.

The constructor is a plain (not suspend) call and sends nothing. The object connects on its first call.

Properties ​

propertytype
projectIdStringthe Project ID
serviceStringthe project's service ID, read from the Project ID
ownerStringthe project owner's ID, read from the Project ID
versionString"2.4.1" (also the constant SKAPI_VERSION)
userJsonObject?the signed-in profile (a copy), or null. See user.
sessionSkapiSession?the signed-in session's tokens: idToken, accessToken, refreshToken (each a String), or null

Errors ​

codemessage
INVALID_PARAMETERProject ID is required. / Project ID is invalid. (thrown by the constructor)
INVALID_PARAMETER"encryption.iterations" must be at least 100000. (thrown by the constructor)
NOT_EXISTSThe project ID does not exist. Create your project from skapi.com (thrown by the first call)

getConnectionInfo ​

kotlin
suspend fun getConnectionInfo(refresh: Boolean = false): JsonObject
java
CompletableFuture<Map<String, Object>> getConnectionInfo(boolean refresh)
// also getConnectionInfo()

The project's name and settings, and the caller as the server sees it. refresh = true asks the server again instead of using the answer from the first call.

json
{
    "project_id": "...",
    "user_ip": "203.0.113.7",
    "user_agent": "okhttp/4.12.0",
    "user_location": "KR",
    "service_name": "My Project",
    "version": "2.4.1",
    "conf": {"prevent_signup": false, "require_login": false, "anonymous_login": false, "...": "..."},
    "encryption_recovery": {"code": null, "message": "..."}
}

"encryption_recovery" is there only with encryption on and a signed-in user. It holds the user's encryption recovery code on the first call after it was created (their first password login with encryption on), and null after that, with a "message" saying what to do. See Encryption recovery codes.

onForeground ​

kotlin
fun onForeground()
java
void onForeground()

Call when the app comes back to the foreground, as skapi-js does on the browser's visibilitychange. A temporary account is checked with the server at once (unless it was confirmed in the last minute) and signed out if it was deleted, and the realtime connection is pinged, or reopened now if it dropped. Returns at once; the work runs in the background. skapi-android's SkapiLifecycle calls it for you.

onNetworkAvailable ​

kotlin
fun onNetworkAvailable()
java
void onNetworkAvailable()

Call when the network comes back, as skapi-js does on the browser's online event. The same checks as onForeground. skapi-android's SkapiLifecycle calls it for you.

close ​

kotlin
fun close()
java
void close()  // SkapiJava also cancels the calls still running

Closes the realtime connection, stops this object's background timers (the temporary account keep-alive, the realtime keep-alive and reconnects) and releases its network threads, so a JVM program can exit. The session stays saved in storage. Do not use the object after close(); make a new one.

FetchOptions ​

kotlin
FetchOptions(
    limit: Int? = null,
    ascending: Boolean? = null,
    startKey: JsonElement? = null,
    fetchMore: Boolean = false,
)
java
FetchOptions fetchOptions = new FetchOptionsBuilder()
    .limit(100)           // int
    .ascending(false)     // boolean
    .startKey("start")    // Object: an earlier answer's "startKey" (a Map), "start" or "end"
    .fetchMore(true)      // boolean
    .build();             // leave out any setting you do not need

Paging options for every method that returns a list (getRecords(), getUsers(), getSubscriptions(), getTickets() and the others). See Paging.

option
limititems per page, up to 1000. The server's default is 50 unless the method says otherwise.
ascendingthe sort direction
startKeywhere to start: the startKey of an earlier answer, JsonPrimitive("start") to start over, or JsonPrimitive("end")
fetchMoretrue reads the next page of the same query, continuing from the last answer

A list answer is a JsonObject with list, startKey, endOfList and startKeyHistory.

SkapiStorage ​

kotlin
interface SkapiStorage {
    fun getItem(key: String): String?
    fun setItem(key: String, value: String)
    fun removeItem(key: String)
}
java
public interface SkapiStorage {
    String getItem(String key);  // or null
    void setItem(String key, String value);
    void removeItem(String key);
}

Where the signed-in session is kept. Keys and values are strings, the same keys skapi-js keeps in localStorage. The methods are called on background threads, sometimes from several at once.

class
MemoryStorage()the default: kept for the life of the Skapi object
FileStorage(path: String)one JSON file. ~/ is the home folder. Created readable by its owner only where the system has POSIX permissions. Writes go to a temporary file first, then replace the old one.
SharedPreferencesStorage(context, name = "skapi-session", encrypt = true)skapi-android: the app's private preferences, each value sealed by the Android Keystore. See Android.

JSON helpers ​

kotlin
fun jsonOf(vararg pairs: Pair<String, Any?>): JsonObject
fun jsonArrayOf(vararg items: Any?): JsonArray
fun Any?.toJsonElement(): JsonElement
fun JsonElement.toJsString(): String
java
// Java uses SkapiJson (com.skapi.java) instead
static Map<String, Object> obj(Object... keysAndValues)
static List<Object> list(Object... items)
static JsonElement fromJava(Object value)
static String stringify(Object value)
static Object parse(String text)
helper
jsonOf("key" to value, ...)a JsonObject from pairs
jsonArrayOf(a, b, ...)a JsonArray from values
toJsonElement()a Map, List, Array, String, number, Boolean, null or JsonElement as JSON. Anything else becomes its toString() text.
toJsString()compact JSON text, as JSON.stringify writes it: whole numbers without .0

See JSON in and out.

SkapiException ​

kotlin
class SkapiException(
    override val message: String,
    val code: String = "ERROR",
    cause: Throwable? = null,
    val details: JsonElement? = null,
) : Exception
java
public final class SkapiException extends Exception {
    public SkapiException(String message, String code, Throwable cause, JsonElement details)
    public String getMessage()
    public String getCode()
    public JsonElement getDetails()  // or null
}
// a failed SkapiJava future: get() throws ExecutionException, getCause() is the SkapiException

What every method throws. code is a short name such as INVALID_PARAMETER; details is what the server sent with the error, when it sent more than a message. See Errors.

skapi-kotlin 2.4.1