Period Tagging SDK Quickstart Guide

Period Tagging SDK enables your application to capture ride-share driver’s different driving periods. This documentation includes everything needed to successfully integrate the Period Tagging SDK on Android Platform.

If you have any additional questions around using the Period Tagging SDK please contact your Arity Customer Success representative.

All requests to Arity require authentication and all applications must be registered with us.


Set-up a new user

  1. Client ID and Client Secret
    Get your Client ID and Client Secret. These have already been created and approved by Arity, and have been sent to you. Contact us if you need help locating them.
  2. B2B-Scope Access Token
    Every call to Period Tagging requires authorization through a B2B-scope access token. You will need to do this step before registering a user and to get a mobile-scope token for that user.
    Use generateToken to generate a B2B-scope access token by sending your Client ID and Client Secret. This access token expires every hour and must be passed in the header of all subsequent API calls.

    Your request should look like this

    client_id			[YOUR client_id]
    client_secret 			[YOUR client_secret]
    grant_type			“client_credentials” 
    scope				“b2b”
    

    *Note: Needed for client back-end access to the Arity platform.

  3. Register User
    Each user in your organization must be registered with Period Tagging. In Period Tagging, "user" refers to the driver.
    New user - Use the createUser method to create a new user. You can specify the userId or let Arity auto-generate it for you. For an auto-generated userId assign NULL into the userId field or remove the key-value pair entirely.
  4. Mobile-Scope Access Token
    Each registered user needs a mobile-scope access token created within Period Tagging. You will provide this access token to the SDK when initializing it.
    Use generateToken to generate a mobile-scope access token by sending your Client ID and Client Secret. This access token expires every hour and must be passed in the header of all subsequent API calls.

    Your request should look like this

    client_id			[YOUR client_id]
    client_secret 			[YOUR client_secret]
    grant_type			“client_credentials” 
    scope				“mobile”
    user_id				[USER'S user_id]
    device_id			[USER'S current device_id]
    

    The cURL script of that request is

    curl -X POST \
      https://api.arity.com/platform/oauth/v1/token \
      -H 'Cache-Control: no-cache' \
      -H 'Content-Type: application/x-www-form-urlencoded' \
      -H 'Postman-Token: cf1c6e73-4ce2-4f27-a7e6-3895c17e6738' \
      -d 'client_id={{client_id}}&client_secret={{client_secret}}&grant_type=client_credentials&scope=mobile&userId=cool-user&deviceId=befc3842-71ed-44f2-8158-145f1078cc11'
    

    The response format is

    {
        "access_token": "USER_MOBILE_SCOPE_TOKEN",
        "token_type": "bearer",
        "expires_in": "0",
        "scope": "mobile"
    }
    

    *Note: Needed for end-user device access to the Arity platform. You will provide the mobile-scope access token in the SDK when initializing it.

SDK Integration

Period Tagging can only be integrated with Android SDK version 19 or newer.

  1. Place SDK File
    Place the Period-Detection-SDK-[CURRENT-VERSION].aar file you received from your Arity customer success representative into the /libs folder in the root of your application.
    *Note: Make sure to update the [CURRENT-VERSION] to match the .aar file name you were provided.
  2. Gradle Integration
    Add the following block of code to your build.gradle file within the android tag
    repositories {
        flatDir {
            dirs '/libs'
        }
    }
    

    and the following within the dependencies tag

    implementation(name: "Period-Detection-SDK-[CURRENT-VERSION]", ext: 'aar')
    implementation 'com.squareup.okhttp3:okhttp:3.11.0'
    
  3. Android Manifest Update
    Add the following block of code to your AndroidManifest.xml file within the application tag
    <service>
        android:name="com.arity.period_detection.PeriodDetectionService"
        android:permission="android.permission.BIND_ACCESSIBILITY_SERVICE">
    
        <intent-filter>
            <action android:name="android.accessibilityservice.AccessibilityService" />
        </intent-filter>
    </service>
    
  4. Initialize SDK
    Import the following line to classes where PeriodDetectionManager is used
    import com.arity.period_detection.PeriodDetectionManager;

    Call the initializer in your main application file

    PeriodDetectionManager periodDetectionManager = PeriodDetectionManager.initialize(this);

    Set the user token in the instance of PeriodDetectionManager using the Mobile-Scope Token that you initialized earlier with the following line

    periodDetectionManager.setAuthorizationToken(USER_MOBILE_SCOPE_TOKEN);

    *Note: If PeriodDetectionManager is initialized in a class other than MainActivity be sure to add the following code within the application tag of AndroidManifest.xml

    android:name=".[APPLICATION_CLASS_NAME]"

Post Integration

  1. Request Accessibility Service Permissions
    The SDK requires accessibility permission in order to work. To ask the user for accessibility service permission, use the following code
    startActivity(new Intent(Settings.ACTION_ACCESSIBILITY_SETTINGS));

    This will navigate the user to the Android accessibility settings screen, not the settings page for your app.

    *Note: In order for the user to turn on accessibility permission they will need to find your app, switch the setting to On, then select OK.

    **Note: The SDK will not work without this permission.

  2. Data Validation
    To validate period data has successfully been sent to Arity, log into the Shared Mobility dashboard with your Arity username and password.
    https://shared-mobility.allstate.com/period-events

    Enter the driver's userID and date from the event generated by the SDK and hit submit to see the test events.

Troubleshooting

You will use generateToken API for both the B2B-scope access token and the Mobile-scope access token. Make sure you have identified the correct scope in your call.


Authorization

Method
Description

POST

generateToken

https://api.arity.com/platform/oauth/v1/token

Generate an access token that you can use for authorization on subsequent API calls.

Users

Method
Description

POST

createUser

https://api.arity.com/registration/v2/users/products

Create a new end-user on the Arity platform, and register that user to a product (in this case, Driving Behavior).

© 2019 Arity, LLC. All rights reserved.  | Privacy Policy | Terms of Use | Legacy APIs