JarCastingFile Selector Gradle and Maven plugin for adding Squencing.com's Real-Time Personalization technology to Android and Java apps
This Gradle and Maven plugin can be used to quickly add a File Selector to your app. By adding this File Selector to your app, you're app user will be able to select a file stored securely in the user's Sequencing.com account. Your app will then be able to use the genetic data in this file to provide the user with Real-Time Personalization.
While the File Selector works out-of-the-box, it is also fully customizable.
A 'Master Maven Plugin' is also available. The Master Plugin contains a customizable, end-to-end solution that quickly adds all necessary code to your app for Sequencing.com's Real-Time Personalization.
Once the Master Plugin is added to your app all you'll need to do is:
- add your OAuth2 secret
- add one or more App Chain numbers
- configure your app based on each app chain's possible responses
To code Real-Time Personalization technology into apps, developers may register for a free account at Sequencing.com. App development with RTP is always free.
Contents
- Implementation
- Gradle integration
- App chains
- Authentication flow
- Steps
- Related repos
- Resources
- Maintainers
- Contribute
Implementation
To implement oAuth2 authentication for your app:
-
Register for a free account
-
Add Sequencing.com's oAuth2 code from this repo to your app
-
Generate an OAuth2 secret and insert the secret into the OAuth2 code
Once OAuth2 authentication is implemented, select one or more app chains that will provide information you can use to personalize your app.
Gradle integration
You need to follow instructions below if you want to build in and use OAuth logic in your existing or new project.
-
create a new Android Gradle based project (i.e. in Android Studio or Eclipse)
-
File selector module prepared as separate module, but it depends on a SequencingOAuth2Client instance from oAuth module. File selector can execute request to server for files with SequencingOAuth2Client instance only. Thus you need 2 modules to be installed: oAuth module and File Selector module
-
add gradle dependency
- see gradle guides
- add dependency into build.gradle file in dependencies section. Here is dependency declaration example:
dependencies { compile 'com.sequencing:file-selector:1.0.30' compile 'com.sequencing:android-oauth:1.0.22' } -
integrate autherization functionality
- add imports
import com.sequencing.androidoauth.core.OAuth2Parameters; import com.sequencing.androidoauth.core.ISQAuthCallback; import com.sequencing.fileselector.core.ISQFileCallback; import com.sequencing.androidoauth.core.SQUIoAuthHandler; import com.sequencing.fileselector.core.SQUIFileSelectHandler; import com.sequencing.oauth.config.AuthenticationParameters; import com.sequencing.oauth.core.Token; -
oAuth Gradle plugin reference: Maven-Android-OAuth-Java
-
integrate autherization functionality reference: Maven-Android-OAuth-Java
-
integrate file selector functionality
- save SequencingOAuth2Client instance of authentication flow
- implement ISQFileCallback
/** * Callback for handling selected file * @param entity selected file entity * @param activity activity of file selector */ void onFileSelected(FileEntity entity, Activity activity);-
create SQUIFileSelectHandler instance that is handling file selection process
-
register your file selection handler by invoking
selectFilemethod with stored SequencingOAuth2Client and callback -
when you invoke
selectFilemethod will be started file selector UI -
when user selects any file and clics on "Continue" button in UI will be invoked user ISQFileCallback implementation and passed to him FileEntity object and current file selector activity
-
each file is represented as FileEntity object with following keys and values format:
key name type description DateAdded String date file was added Ext String file extension FileCategory String file category: Community, Uploaded, FromApps, Altruist FileSubType String file subtype FileType String file type FriendlyDesc1 String person name for sample files FriendlyDesc2 String person description for sample files Id String file ID Name String file name Population String Sex String the sex
-
examples
- example of
My files
- example of
Sample files
- example of
Select Filebutton
Button btnFileSelector = (Button)findViewById(R.id.btnFileSelector);- example of SQUIFileSelectHandler initialization
SQUIFileSelectHandler fileSelectHandler = new SQUIFileSelectHandler(this);- example of
selectFilemethod
fileSelectHandler.selectFile(OAuth2Parameters.getInstance().getOauth(), new ISQFileCallback() { @Override public void onFileSelected(FileEntity entity, Activity activity) { Log.i(TAG, "File has been selected"); Toast toast = Toast.makeText(getApplicationContext(), entity.toString(), Toast.LENGTH_LONG); toast.show(); } }, true, false); - example of
App chains
Search and find app chains -> https://sequencing.com/app-chains/
Each app chain is composed of
- an API request to Sequencing.com
- this request is secured using oAuth2
- analysis of the app user's genes
- each app chain analyzes a specific trait or condition
- there are thousands of app chains to choose from
- all analysis occurs in real-time at Sequencing.com
- an API response to your app
- the information provided by the response allows your app to tailor itself to the app user based on the user's genes.
- the documentation for each app chain provides a list of all possible API responses. The response for most app chains are simply 'Yes' or 'No'.
Example
- App Chain: It is very important for this person's health to apply sunscreen with SPF +30 whenever it is sunny or even partly sunny.
- Possible responses: Yes, No, Insufficient Data, Error
While there are already app chains to personalize most apps, if you need something but don't see an app chain for it, tell us! (ie email us: [email protected]).
Authentication flow
Sequencing.com uses standard OAuth approach which enables applications to obtain limited access to user accounts on an HTTP service from 3rd party applications without exposing the user's password. OAuth acts as an intermediary on behalf of the end user, providing the service with an access token that authorizes specific account information to be shared.
Steps
Step 1: Authorization Code Link
First, the user is given an authorization code link that looks like the following:
https://sequencing.com/oauth2/authorize?redirect_uri=REDIRECT_URL&response_type=code&state=STATE&client_id=CLIENT_ID&scope=SCOPES
Here is an explanation of the link components:
- https://sequencing.com/oauth2/authorize: the API authorization endpoint
- client_id=CLIENT_ID: the application's client ID (how the API identifies the application)
- redirect_uri=REDIRECT_URL: where the service redirects the user-agent after an authorization code is granted
- response_type=code: specifies that your application is requesting an authorization code grant
- scope=CODES: specifies the level of access that the application is requesting
Step 2: User Authorizes Application
When the user clicks the link, they must first log in to the service, to authenticate their identity (unless they are already logged in). Then they will be prompted by the service to authorize or deny the application access to their account. Here is an example authorize application prompt
Step 3: Application Receives Authorization Code
If the user clicks "Authorize Application", the service redirects the user-agent to the application redirect URI, which was specified during the client registration, along with an authorization code. The redirect would look something like this (assuming the application is "php-oauth-demo.sequencing.com"):
https://php-oauth-demo.sequencing.com/index.php?code=AUTHORIZATION_CODE
Step 4: Application Requests Access Token
The application requests an access token from the API, by passing the authorization code along with authentication details, including the client secret, to the API token endpoint. Here is an example POST request to Sequencing.com token endpoint:
https://sequencing.com/oauth2/token
Following POST parameters have to be sent
- grant_type='authorization_code'
- code=AUTHORIZATION_CODE (where AUTHORIZATION_CODE is a code acquired in a "code" parameter in the result of redirect from sequencing.com)
- redirect_uri=REDIRECT_URL (where REDIRECT_URL is the same URL as the one used in step 1)
Step 5: Application Receives Access Token
If the authorization is valid, the API will send a JSON response containing the access token to the application.
Related repos
Master Plugin is available in the following languages:
File Selector is available in the following languages: File Selector Plugins
- Android (Maven plugin) <-- this repo
- Java (Maven plugin) <-- this repo
- Objective-C (CocoaPod plugin)
- Swift (CocoaPod plugin)
File Selector Code
- Android (code)
- Objective-C (code)
- Swift (code)
- PHP
- Perl
- Python (Django)
- Java (Servlet)
- Java (Spring)
- .NET/C#
Resources
Maintainers
This repo is actively maintained by Sequencing.com. Email the Sequencing.com bioinformatics team at [email protected] if you require any more information or just to say hola.
Contribute
We encourage you to passionately fork us. If interested in updating the master branch, please send us a pull request. If the changes contribute positively, we'll let it ride.
