kin-ecosystem-android-sdk

Disclaimer

The Sample App under module app is for presentation purposes only - it should not be used for any other purpose.
The backend service supporting the ecosystem sdk is in test mode and SLA is not guarantee.
All blockchain transactions are currently running on Stellar test net and not on main net.

Intro

The ecosystem "5 minute SDK" supports rich user experience and seamless blockchain integration.

Once the ecosystem SDK is integrated within a digital service, you’ll have the ability to provide your users with a range of new experiences as part of the Kin ecosystem including, earn and spend marketplace opportunities, and the ability to view their account balance and order history
A stellar wallet and account will be created behind the scene for the user.

Registration for Ecosystem backend service

Digital service application needs to initiate the Ecosystem sdk, which interacts with the ecosystem backend service.

The Ecosystem backend is required for

Creating users accounts on the Stellar blockchain
Funds these account with initial XLM balance.
Serving KIN earn and spend offers for the SDK marketplace.
Mange and store user's earn and spend order history.

Therefore the ecosystem backend will block unauthorized requests. Digital services will have to authorised client request using one of the following methods:

"whitelist" registration - used for quick first time integration or small internal testing.
1. Whitelist registration requires a unique appID and apiKey.
2. Please contact us to receive your unique appId and apiKey.
"JWT" registration - A secure register method for production ready application,
1. "JWT" registration" use a Server side signed JWT token to authenticated client request.
2. You can learn more here
3. Please contact us to receive your JWT issuer identifier (iss key) and provide us with your public signature key and its corresponding 'keyid'

JWT Registration specs

We will support ES256 signature algorithm later on, right now you should use RS512.

The header will follow this template

{
    "alg": "RS512", // We will support ES256 signature algorithem 
    "typ": "JWT",
    "kid": string" // identifier of the keypair that was used to sign the JWT. identifiers and public keys will be provided by signer authority. This enables using multiple private/public key pairs (a list of public keys and their ids need to be provided by signer authority to verifier in advanced)
}

Here is the registration payload template

{
    // common/ standard fields
    iat: number;  // issued at - seconds from epoc
    iss: string; // issuer - please contact us to recive your issuer
    exp: number; // expiration
    sub: "register"

    // application fields
    user_id: string; // id of the user - or a deterministic unique id for the user (hash)
}

Setup sample app

The Sample app is configured with default appId = 'test' and apiKey = 'A2XEJTdN8hGiuUvg9VSHZ'.
These appID and apiKey can be used for integration testing in any app but will not run on real production environment.
To setup and run the sample app an authorized apiKey and appId needs to be provided.
Contact us to receive your unique appId and apiKey.

To override the default setting, create or edit a local credential.properties in the app module directory.
Add the lines below to your local credential.properties file of the sample app once you receive your appId and apiKey.

   APP_ID="YOUR_APP_ID" // will be used for Whitelisted registartion and also as the issuer (iss). Set by defualt to 'test' 
   API_KEY="YOUR_API_KEY" // only requreid for whitelist registrartion. Set by default to 'A2XEJTdN8hGiuUvg9VSHZ'.
   RS512_PRIVATE_KEY="YOUR_RS512_PRIVATE_KEY // (optional) only required when testing JWT on sample app in real use case JWT is created by server side with ES256 signature
   IS_JWT_REGISTRATION = false// (optional)to test sample app JWT registartion set this property to true, if not specified defualt is set to false

The sample app Gradle build loads credential.properties setting and uses it to create the 'SignInData' object used for the registration.

Integrating 5 minutes SDK within digital service

As can be seen in the sample app, there are just few step required to integrate the SDK.

Add this to your project module's build.gradle file.

 repositories {
     ...
     maven {
         url 'https://jitpack.io'
     }
 }

Add this to the app module's build.gradle file.

 dependencies {
     ...
     implementation 'com.github.kinfoundation:kin-ecosystem-android-sdk:0.0.6

 }

 ```

Create SignInData object and set userID, appID, apiKey etc.

Option 1 - Should be use only for first time rapid integration and internal testing.

      signInData = new SignInData()
           .signInType(SignInTypeEnum.WHITELIST)
           .appId("appID")
           .deviceId("deviceUUID")
           .userId("userID"")
           .apiKey("apiKey");

Option 2 - recommended integration using JWT token signed by digital service server side.

      signInData = new SignInData()
            .signInType(SignInTypeEnum.JWT)
            .jwt("jwt")
            .deviceId("deviceUUID")

JWT spec can be found at ecosystem-api repository

Initiate the SDK when the application starts calling Kin. The first start will begin the blocakchain wallet and account creation process.

         try {
             Kin.start(getApplicationContext(), signInData);
         } catch (InitializeException e) {
             //
         }

Launch the marketplace experience.

     try {
         Kin.launchMarketplace(MainActivity.this);
          System.out.println("Public address : " + Kin.getPublicAddress());
          } catch (TaskFailedException e) {
            //
      }

Create Native Spend Offer

A native spend is a mechanism allowing your users to buy virtual goods you define, using Kin on Kin Ecosystem API's. (see more)

Create Native EARN Offer

A native earn is a mechanism allowing your users to earn Kin as a reward for native tasks you define, such as setting a profile picture or adding info. (see more)

License

The kin-ecosystem-android-sdk library is licensed under MIT license.

yosriz / kin-ecosystem-android-sdk