SDK Specifications

Overview

This topic defines the API specifications required to configure SDK for Universal ID partners. It is a one-time configuration to enable partnering with multiple Universal ID partners.

Implementation Workflow

Here is an overview of how the general workflow looks like for implementing UnifID.

Initialize the app using InMobi Init API.
Prompt the UI screen to receive the email/mobile number/username.
Hash the PII data using MD5, SHA1, and SHA 256 algorithms.
Use the UnifID Push API to send the identity details to InMobi’s server.
Initialize the mediation platform’s SDK.

Prerequisite

Publishers using mediation partners need to initialize the InMobi SDK before initializing the mediation SDK.
You must initialize the InMobi SDK before you use InMobiUnifiedIdService API.
If you are a new user, you must call the InMobiUnifiedIdService.reset()before InMobiUnifiedIdService.push(userDataModel).
You must call InMobiUnifiedIdService.push(userDataModel) for every session.
The app would have access to the user's PII (Personally Identifiable Information) data like email, phone number, and so on that need to be passed in as hashed values to the identity partners to fetch the universal ids.

IMUnifiedIdService Specification

IMUnifiedIdService is a new class and it consists of the following APIs.

API	Syntax	Description
Push	push(data: IMUserDataModel)	You should use this API to submit the hashed PII data to the InMobi Id Service. Every time you call this API, the SDK makes a request to InMobi ID Service. It is recommended for you to call this API at the beginning of every app session.
Fetch	fetchUnifiedIds(delegate: UnifiedIdInterface)	You should use this to get the UnifIDs. If the UnfIDs expire, the InMobi Id service receives the call to refresh the IDs that are passed to you.
Reset	reset()	You should use this API to clear all the UnifIDs and signatures stored locally in the SDK.

IMUserDataTypes and IMUserDataModel

IMUserDataTypes class holds the different variants of user-data that you pass. First, you should create an instance of IMUserDataTypes and set the corresponding values for the IMUserDataModel instance. The system passes the instance IMUserDataModel to fetch the function.

IMUserDataTypes

Property	Type	Purpose
md5	String	To provide hashed data using md5 hashing algorithm.
sha1	String	To provide hashed data using SHA1 hashing algorithm.
sha256	String	To provide hashed data using SHA256 hashing algorithm.

IMUserDataModel

Property	Type	Purpose
phoneNumber	IMUserDataTypes	To provide phone number in different variants (md5, sha1, etc.).
emailId	IMUserDataTypes	To provide email id in different variants (md5, sha1, etc.)
Extras	Dictionary	To provide any extra information.

Please note some data types such as email ID are a prerequisite for some Identity partners.

Callbacks

SDK calls the “onFetchCompleted” function to notify you about the successful submission of the hashed PII data to the InMobi ID Service. It also shares the list of Universal IDs in the form of a dictionary. SDK doesn't return any expired Universal IDs and calls this function only on the Main Thread.

Function	Syntax
onFetchCompleted	onFetchCompleted(response: Dictionary?, error: Error?)

If you set an error object, the SDK calls this function to notify you about the error while submitting the hashed PII data to the InMobi Id Service.

IMSDK

You should use this function to pass the UIDs obtained by having direct partnerships with different ID partners (eg. liveramp, id5, etc.), upstream to demand partners, or to other ad exchanges. It helps you to monetize your inventory across the ecosystem. Essentially, it is an existing API within the SDK that enables you to pass universal IDs to InMobi. When both UID and SDK's UnifID service data are present, SDK’s UnifID service takes higher precedence.

Function	Syntax
setPublisherProvidedUnifiedId	setPublisherProvidedUnifiedId(ids: Dictionary)

Internal APIs

To create an ad request, the SDK uses the getUids API internally.

Function	Syntax
getUids	getUids() -> Dictionary?