Skip to main content

Example App

You can find an executable example app in the source with several calls to the SDK, which can guide you through your development.

Initial Setup​

  1. Clone Repository: Clone the polygonid-android-sdk repository.

  2. Run the app:

    ./gradlew installDebug app

General Flow​

Overview​

In the upcoming sections, we shall see the general flow of how to use the Polygon ID SDK plugin. The steps are summarised as:

A. Identity

  1. Initialize Polygon ID SDK.
  2. Create an Identity for the wallet.
  3. Retrieve Identifier from the Identity created in the previous step.
  4. Remove Identity (only if required).
  5. Get iden3Message from Issuer.
  6. Authenticate Identity using Identifier, iden3Message, and Private Key.

B. Credential

  1. Create CredentialRequestEntity from the Iden3Message received from an Issuer.
  2. Fetch and Save credentials (received from Issuer) on SDK using CredentialRequestEntity, Identifier, and Private Key.
  3. Get credentials that are saved on wallet SDK. One can also retrieve them with credential IDs.
  4. Remove credential (only if required).
  5. Update credential (only if required).

C. Proof

  1. Generate zero-knowledge proof using iden3Message, Identifier, and Private Key.

Initiate Polygon ID SDK​

To start using Polygon ID SDK, an integrator needs to initialize it first. This is done by using:

PolygonIdSdk.init(
    context = context,
    env = EnvEntity(
      blockchain = "polygon",
      network = "amoy",
      web3Url = "https://polygon-amoy.infura.io/v3/",
      web3RdpUrl = "wss://polygon-amoy.infura.io/v3/",
      web3ApiKey = "theApiKey",
      idStateContract = "0x1a4cC30f2aA0377b0c3bc9848766D90cb4404124",
      pushUrl = "https://push-staging.polygonid.com/api/v1"
  ),
)

env is optional and can be set afterward with PolygonIdSdk.getInstance().setEnv()

After the SDK initialization, the Integrator will need to use the instance of PolygonIdSDK PolygonIdSdk.getInstance().

Get current environment​

The current environment can be retrieved using getEnv(), it gives an EnvEntity:

PolygonIdSdk.getInstance().getEnv(context = context)

Get Iden3Message from a String​

An Integrator uses iden3Message to communicate with an Issuer/Verifier. This 'iden3message' is created from the QR code scanned by the user on his/her wallet. The getIden3Message() uses a string message (created after scanning the QR code) as the input parameter and generates iden3Message.

PolygonIdSdk.getInstance().getIden3Message(
    context, theMessage
)

A. Identity​

This part of the flow consists of initialising Polygon ID SDK, creating an identifier for an identity and retrieving it, and using the identifier to authenticate the Identity.

1. Create Identity​

After SDK initialization, the SDK checks the existence of an Identifier that was previously created with the addIdentity() function. If no previously created Identifier is found, the SDK first needs to create an identity first using addIdentity() function.

PolygonIdSdk.getInstance().addIdentity(
    context = context, secret = "theSecret"
)

You can retrieve your private key from the PrivateIdentityEntity specified in the code above. Keep this private key safe; it will be used in a few other SDK methods as you will see in the following steps.

note

It is not mandatory to pass the secret as the input parameter in the function. If you do not pass it, a random secret is generated by the system.

2. Get did Identifier​

This retrieves the did identifier by passing the environment detail and private key input parameter to the getDidIdentifier() function; please note that the private key is generated from PrivateIdentityEntity that we generated via addIdentity() function in the previous section.

PolygonIdSdk.getInstance().getDidIdentifier(
    context = context,
    privateKey = privateKey,
    blockchain = env.blockchain,
    network = env.network,
)

3. Remove Identity​

To remove an existing Identity (use this only when required), you need to call the removeIdentity() with did identifier and the privateKey as the input parameters.

PolygonIdSdk.getInstance().removeIdentity(
    context = context,
    privateKey = privateKey,
    genesisDid = didIdentifier
)

4. Authenticate Identity​

The authentication includes two steps:

  • Get an iden3message from the QR code as seen on 2.
  • Authenticate Identity using iden3message

We use authenticate() to authenticate an identity by using privateKey, did identifier, and iden3Message as the input parameters.

PolygonIdSdk.getInstance().authenticate(
    context = context,
    message = message as Iden3MessageEntity.AuthIden3MessageEntity,
    genesisDid = did,
    privateKey = privateKey
)

B. Credential​

This part of the flow consists of retrieving credentials from an Issuer and saving them in the wallet. One or more credentials can be retrieved and one or more credentials can be removed from the wallet.

1. Fetch and Save Credentials​

This functionality consists of retrieving credentials from an Issuer (by fetching them) and then saving them on the wallet.

This involves:

  • Get an iden3message from the QR code as seen on 2.
  • Fetching and saving credentials using CredentialRequestEntity, identifier, and privateKey.
PolygonIdSdk.getInstance().fetchAndSaveClaims(
    context = context,
    message = message as Iden3MessageEntity.OfferIden3MessageEntity,
    genesisDid = did,
    privateKey = privateKey
)

2. Get Credentials​

Once credentials have been saved on the wallet SDK, these can be retrieved by the Integrator using getClaims() with did identifier, and privateKey used as the mandatory input parameters and filters as an optional one. Filters lets an Integrator get credentials based on some pre-determined criteria.

PolygonIdSdk.getInstance().getClaims(
    context = context,
    genesisDid = did,
    privateKey = privateKey,
    filters = filters
)

3. Get Credentials by Ids​

This functionality lets an Integrator get credentials from an Issuer based on their IDs. The list of IDs claimIds, did identifier, and privateKeyare passed as input parameters to the getClaimsByIds() function and a list of credentials in the form of ClaimEntity is retrieved.

PolygonIdSdk.getInstance().getClaimsByIds(
    context = context,
    genesisDid = did,
    privateKey = privateKey,
    claimIds = listOf(id)
)

4. Remove a Credential​

A credential can be removed from the wallet using removeClaim() by passing claimId (the ID of the credential to be removed), the did identifier and the privateKey as the input parameters.

PolygonIdSdk.getInstance().removeClaim(
    context = context,
    genesisDid = did,
    privateKey = privateKey,
    claimId = id
)

5. Remove Multiple Credentials​

This is similar to removing a single credential described above. In this case, you need to pass a list of claimIds to be removed, the did identifier, and the privateKey as the input parameters to removeClaims().

PolygonIdSdk.getInstance().removeClaims(
    context = context,
    genesisDid = did,
    privateKey = privateKey,
    claimIds = ids
)

6. Update Credential​

To update a credential, the updateClaim() function is used with the following fields passed as input parameters:

  • claimId
  • identifier
  • privateKey
  • other information such as identity state, issuer, credential's expiration date, type of credential, etc.
PolygonIdSdk.getInstance().updateClaim(
    context = context,
    claimId = claimId
    genesisDid = did,
    privateKey = privateKey,
    state: theState,
    expiration: theExpiration,
    type: theType,
    data: theData,
)