Scrella Flutter SDK Documentation

Partner Integration Guide

Introduction

The Scrella Flutter SDK provides a comprehensive set of interfaces that enable partners to seamlessly integrate device health check capabilities directly into their applications. This allows partners not only to embed Scrella's technology but also to retain full control over the user experience within their own product environments.

The SDK exposes APIs that support key customer journeys, including:

By leveraging the Scrella Flutter SDK, partners can deliver a fully integrated device protection experience while maintaining ownership of their application flow, branding, and customer interactions.

Initialization

Initialize Scrella Flutter SDK ApiClient in the main method. This is a singleton that will handle all the network request between the SDK and Scrella backend.

Sample Code

void main() async {
    ...
    ScrellaApiClient.initialize(partnerApiKey: /* scrella-partner-api-key */);
    ...
}

Parameters

Parameter Type Required Default Description
partnerApiKey String Yes - Partner-issued API Key

Check If User Is Authenticated

Use this API to check if a user is already authenticated within the SDK. If it returns true, proceed to the dashboard and call the Account Status endpoint to retrieve the user's current information.

Future<bool> ScrellaIdentityApi.isLoggedIn()

Account Status

This API retrieves comprehensive user data for the authenticated account, including device information, subscription status, and other details necessary to manage user workflows and personalize the application experience.

Future<void> ScrellaStatusApi.getStatus({
    Function(bool val)? setLoading,
    Function(String message, int? statusCode)? onError,
    Function(UserStatusResponse?, String?)? onSuccess,
})

Parameters

Parameter Type Required Default Description
setLoading Function No - A callback function that communicates the loading status during the operation, enabling you to control and display loading indicators in your application.
onError Function No - A callback function invoked when an error occurs, providing the error message and optional HTTP status code for error handling and user feedback.
onSuccess Function No - A callback function invoked on successful retrieval of user status, returning a UserStatusResponse object with comprehensive account and device information.

UserStatusResponse

final String imeiUrl;
final UserInfo userInfo;
final int onboardingStatus;
final int deviceHealthCheckStatus;
final DeviceHealthInfo deviceHealthInfo;
final SubscriptionPlan? activePlan;
final double walletBalance;
final String? fplTeam;
final DeviceInfoData deviceInfo;

UserInfo

final int userId;
final String userIdentifier;
final String firstName;
final String lastName;
final String email;
final String phoneNumber;
final bool isKYCVerified;
final String referralCode;
final double referralBonusBalance;
final double? walletBalance;

DeviceHealthInfo

final int frontCameraHealthStatus;
final String frontCameraHealthMessage;
final int backCameraHealthStatus;
final String backCameraHealthMessage;
final int screenSensorHealthStatus;
final String screenSensorHealthMessage;
final int screenGlassHealthStatus;
final String screenGlassHealthMessage;

SubscriptionPlan

final int id;
final int planId;
final String planName;
final String startTime;
final String startTimeFormatted;
final String waitPeriodExpiryTime;
final String expiryTime;
final String expiryTimeFormatted;
final String proofOfPayment;
final String insuranceCertificate;
final int status;
final String iconDark;
final String iconLight;

DeviceInfoData

final int id;
final List<String> imei;
final String deviceModel;
final String modelNo;
final int? deviceHealthStatus;
final double? healthRating;
final int status;
final int? deviceHealthCheckStatus;
final int onboardingStatus;
final bool canReceiveFPLNotifications;
final String timeCreated;
final String timeUpdated;

Register

Future<void> ScrellaIdentityApi.register(
    SignUpPayload payload, {
    void Function(bool val)? setLoading,
    void Function(String message, int? statusCode)? onError,
    void Function(ScrellaSignupResponse?, String?)? onSuccess,
})

Parameters

Parameter Type Required Default Description
payload SignUpPayload Yes - The payload object containing user information required for successful registration on Scrella.
setLoading Function No - A callback function that communicates the loading status during the operation, enabling you to control and display loading indicators in your application.
onError Function No - A callback function invoked when an error occurs, providing the error message and optional HTTP status code for error handling and user feedback.
onSuccess Function No - A callback function invoked upon successful completion of the onboarding operation, returning a ScrellaSignupResponse object containing the registration result data.

SignUpPayload

final String firstName;
final String lastName;
final String emailAddress;
final String phoneNumber;
final bool isTermsConditionsAgreed;
final String pushNotificationToken;

ScrellaSignupResponse

final String jwt;
final String imeiUrl;

Login

This route is necessary because email addresses and phone numbers are unique identifiers for Scrella customers. Existing Scrella customers cannot use the registration route. If you receive a message indicating that the email address or phone number already exists, the user should proceed with the login route instead.

Future<void> ScrellaIdentityApi.login(
    String emailOrPhoneNo, {
    Function(bool val)? setLoading,
    Function(String message, int? statusCode)? onError,
    Function(AuthDataResponse?, String?)? onSuccess,
})

Parameters

Parameter Type Required Default Description
emailOrPhoneNo String Yes - Email address or phone number of the user trying to login. Phone number must contain country code, for example: +2348012345678
setLoading Function No - A callback function that communicates the loading status during the operation, enabling you to control and display loading indicators in your application.
onError Function No - A callback function invoked when an error occurs, providing the error message and optional HTTP status code for error handling and user feedback.
onSuccess Function No - A callback function invoked upon successful login attempt, returning an AuthDataResponse object containing the login attempt response data.

AuthDataResponse

final int id;
final String email;
final String phoneNumber;

Resend Login OTP

After a successful login attempt, a One-Time-Password is sent to the user's email address and phone number. Use this API to resend the login OTP if the user doesn't receive it. The API is throttled to one request per minute per IP address.

Future<void> ScrellaIdentityApi.resendOtp(
    int requestId, {
    Function(bool val)? setLoading,
    Function(String message, int? statusCode)? onError,
    Function(String message)? onSuccess,
})

Parameters

Parameter Type Required Default Description
requestId Integer Yes - The request ID returned from the initial login attempt via AuthDataResponse.id
setLoading Function No - A callback function that communicates the loading status during the operation, enabling you to control and display loading indicators in your application.
onError Function No - A callback function invoked when an error occurs, providing the error message and optional HTTP status code for error handling and user feedback.
onSuccess Function No - A callback function invoked upon successful login attempt OTP resend, returning a message indicating whether the OTP was sent successfully.

Confirm Login OTP

Use this API to submit and validate the OTP sent to the user. Upon successful validation, the backend generates and returns a JWT token.

Future<void> ScrellaIdentityApi.confirmOtp(
    ConfirmOtpPayload payload, {
    Function(bool val)? setLoading,
    Function(String message, int? statusCode)? onError,
    Function(ScrellaSignupResponse? data, String? message)? onSuccess,
})

Parameters

Parameter Type Required Default Description
payload ConfirmOtpPayload Yes - The payload object containing data required for successful login OTP confirmation on Scrella.
setLoading Function No - A callback function that communicates the loading status during the operation, enabling you to control and display loading indicators in your application.
onError Function No - A callback function invoked when an error occurs, providing the error message and optional HTTP status code for error handling and user feedback.
onSuccess Function No - A callback function invoked upon successful login OTP confirmation, returning a ScrellaSignupResponse object containing the confirm login OTP response data.

ConfirmOtpPayload

final int requestId;
final String otp;
final DeviceTypeEnum deviceType;
final String pushNotificationToken;

ScrellaSignupResponse

final String jwt;
final String imeiUrl;
DeviceTypeEnum
enum DeviceTypeEnum {
    phone(1),
    tablet(2),
    pos(3),
    laptop(4),
    desktop(5);
}

Device Health Check

Use the ScrellaProvider to handle the device healthcheck flow. The step in the user journey requires importing package:scrella_sdk/scrella_sdk.dart and package:scrella_sdk/state/scrella_provider.dart 

ScrellaProvider(
    imeiUrl: imeiUrl,
    colors: ScrellaColors.defaults(),
    child: EligibilityScreen(
        onEligibilityCompleted: (bool isEligible) {
                //callback for when the tests complete 
        },
    ),
)

Parameters

Parameter Type Required Default Description
imeiUrl String Yes - The IMEI URL obtained from a successful user registration or login, accessible via ScrellaSignupResponse.imeiUrl. Required to complete the device health check process.
colors ScrellaColors Yes - Customize the visual appearance of the device health check screens by adjusting colors to match your brand identity.
child EligibilityScreen Flutter Component Yes - The EligibilityScreen component handles all screens, functions, and features needed to perform the device eligibility check.
child.onEligibilityCompleted Function Yes - A callback function invoked when the user completes all device health checks, returning a boolean value indicating eligibility status.

ScrellaColors

final Color primary;
final Color secondary;
final Color background;
final Color text;
final Color accent;
final Color gray;
final Color backgroundGray;
final Color textGray;
final List<Color> backgroundGradients;

Get device Insurance Plans

This API returns the insurance plan available for device protection.

Future<void> ScrellaUtilitiesApi.getPlans({
    Function(bool val)? setLoading,
    Function(String message, int? statusCode)? onError,
    Function(List<PlanData>?, String?)? onSuccess,
})

Parameters

Parameter Type Required Default Description
setLoading Function No - A callback function that communicates the loading status during the operation, enabling you to control and display loading indicators in your application.
onError Function No - A callback function invoked when an error occurs, providing the error message and optional HTTP status code for error handling and user feedback.
onSuccess Function No - A callback function invoked when device protection plans are successfully retrieved, returning a collection of PlanData objects with detailed information about each available protection plan.

PlanData

final int id;
final String? iconDark;
final String? iconLight;
final String? backPhoto;
final String? name;
final String? primaryTagLine;
final String? secondaryTagLine;
final int? durationInMonths;
final double? amount;
final double? insuranceFee;
final double? cover;
final String? note;
final int? type;
final String? typeText;
final int? status;
final String? statusText;
final int? waitingPeriodInDays;
final List<String> planOfferings;
final List<String> planExclusions;
final List<String> planBenefits;
final String? timeCreated;
final String? timeUpdated;
final int? totalSubscribers;
final int? activeSubscribers;
final double? referralBonus;

Activate Device Protection

After the user has completed payment for a device protection plan, use this endpoint to activate the device protection on Scrella.

Future<void> ScrellaUserPlanApi.activateUserPlan(
    UserPlanPayload payload, {
    Function(bool)? setLoading,
    Function(String message)? onError,
    Function(String message)? onSuccess,
})

Parameters

Parameter Type Required Default Description
payload UserPlanPayload Yes - The payload object containing the information necessary to successfully activate device protection for the user.
setLoading Function No - A callback function that communicates the loading status during the operation, enabling you to control and display loading indicators in your application.
onError Function No - A callback function invoked when an error occurs, providing the error message and optional HTTP status code for error handling and user feedback.
onSuccess Function No - A callback function triggered upon successful device protection activation, returning a message that indicates the operation's completion status.

UserPlanPayload

final int planId;
final double planAmount;
final String nin;
Parameter Type Required Default Description
planId Integer Yes - The plan Id obtained from the PlanData.id field returned by the get plans API.
planAmount Double Yes - The plan amount obtained from the PlanData.amount field returned by the get plans API.
nin String Yes - National Identity Number for KYC

Terminate Device Protection

Use this API to terminate users' active device protection plan.

Future<void> ScrellaUserPlanApi.terminateUserPlan(
    TerminatePlanPayload payload, {
    Function(bool)? setLoading,
    Function(String message)? onError,
    Function(String message)? onSuccess,
  })

Parameters

Parameter Type Required Default Description
payload TerminatePlanPayload Yes - The payload object containing the information necessary to successfully terminate device protection for the user.
setLoading Function No - A callback function that communicates the loading status during the operation, enabling you to control and display loading indicators in your application.
onError Function No - A callback function invoked when an error occurs, providing the error message and optional HTTP status code for error handling and user feedback.
onSuccess Function No - A callback function triggered upon successful device protection termination, returning a message that indicates the operation's completion status.

TerminatePlanPayload

final int userPlanId;
final int reason;
final String reasonText;
Parameter Type Required Default Description
userPlanId Integer Yes - The Id of the user's active plan obtained from the userStatusResponse.subscriptionPlan.id field returned by the ScrellaStatusApi.getStatus API.
reason Integer Yes - The reason for terminating the plan. This value is obtained from the enum selected by the user.
reasonText String Yes - The reason text for terminating the plan. This is string version of the Enum. This value is obtained from the enum selected by the user. When user selected others, please provide the reason text.

File a Claim

Use this API to provide an inteface that will enable users file claims. For instance, users can upload photos or videos of the damaged device, provide detailed descriptions of the incident, and submit claims directly through your application interface.

Future<void> ScrellaClaimsApi.submitClaim(
    ClaimSubmissionPayload payload, {
    Function(bool val)? setLoading,
    Function(String message, int? statusCode)? onError,
    Function(String)? onSuccess,
})

Parameters

Parameter Type Required Default Description
payload ClaimSubmissionPayload Yes - The payload object containing the information necessary to successfully file a claim.
setLoading Function No - A callback function that communicates the loading status during the operation, enabling you to control and display loading indicators in your application.
onError Function No - A callback function invoked when an error occurs, providing the error message and optional HTTP status code for error handling and user feedback.
onSuccess Function No - A callback function triggered upon successful claim submission, returning a message that indicates the operation's completion status.

ClaimSubmissionPayload

final int deviceId;
final int issue;
final String description;
final List<String> medias; // base64 strings for claims supporting media (video)

Get Claims

This endpoint allows retrieving all claims submitted by the authenticated user, including detailed information about claim status, dates, and associated device information.

Future<void> ScrellaClaimsApi.getClaims({
    Function(bool val)? setLoading,
    Function(String message, int? statusCode)? onError,
    Function(List<ClaimData>?, String?)? onSuccess,
})

Parameters

Parameter Type Required Default Description
setLoading Function No - A callback function that communicates the loading status during the operation, enabling you to control and display loading indicators in your application.
onError Function No - A callback function invoked when an error occurs, providing the error message and optional HTTP status code for error handling and user feedback.
onSuccess Function No - A callback invoked upon successful retrieval of the user's claims, returning a list of ClaimData objects with detailed information for each claim.

ClaimData

final int id;
final String claimIdentifier;
final int status;
final String statusText;
final String statusMessage;
final String timeCreated;
final int issue;
final String issueText;
final String description;
final String vendorUser;
final String vendorBusiness;
final String vendorBusinessAddress;
final String duration;
final bool hasIssue;
final bool canReportIssue;
final int enterpirseId;
final String enterpriseName;
final String enterpriseUser;
final String device;

Get Claim Details

This endpoint allows retrieving all data for a particular claim tied to an authenticated user.

Future<void> ScrellaClaimsApi.getClaimDetails({
    required int claimId,
    Function(bool val)? setLoading,
    Function(String message, int? statusCode)? onError,
    Function(ClaimDetails?)? onSuccess,
})

Parameters

Parameter Type Required Default Description
claimId Integer Yes - The claim Id obtained from the ClaimData.id field returned by ScrellaClaimsApi.getClaims
setLoading Function No - A callback function that communicates the loading status during the operation, enabling you to control and display loading indicators in your application.
onError Function No - A callback function invoked when an error occurs, providing the error message and optional HTTP status code for error handling and user feedback.
onSuccess Function No - A callback invoked when a single claim is successfully retrieved, returning a ClaimDetails object containing comprehensive details about the claim.

ClaimDetails

final int id;
final String claimNo;
final int status;
final int issue;
final String issueText;
final String details;
final String date;
final Device device;

Device

final String brand;
final String model;
final List<String> imei;

Enum/Status Dictionary

UserStatusResponse.onboardingStatus

The table below displays the various OnboardingStatusEnum values and their corresponding descriptions.

Value Key Description
1 OTPVerification User has completed registration but has not yet verified their email or phone number through OTP confirmation. Navigate the user to an OTP confirmation screen and guide the user to complete this process.
2 DeviceTest User has not performed their device health check. Navigate the user to the device health check part of your app, use the SDK to implement this feature.
3 AwaitingDeviceTestResult The user's device health check is currently being processed by the system.
4 DeviceTestFailed The user's device failed the health check. Use UserStatusResponse.DeviceHealthInfo to retrieve the specific reasons for failure and guide the user to address the identified issues before retrying the test.
5 DeviceTestPassed User successfully completed the device health check. Direct the user to select and purchase an insurance plan. Note: If no plan is purchased within 24 hours, the user will be required to repeat the device health check.
6 Completed User has successfully completed the onboarding process and currently maintains an active insurance plan. Retrieve the user's active plan details using the Account Status endpoint via UserStatusResponse.SubscriptionPlan.
7 ClaimSuccessful User has an active claim filed under their device insurance policy
8 PlanTerminated User terminate their device insurance policy

DeviceHealthInfo.frontCameraHealthStatus, DeviceHealthInfo.backCameraHealthStatus, DeviceHealthInfo.screenSensorHealthStatus, DeviceHealthInfo.screenGlassHealthStatus, DeviceInfoData.deviceHealthStatus

The table below displays the various DeviceHealthStatusEnum values and their corresponding descriptions.

Value Key Description
0 Pending Health status for device or device component is yet to be detemined.
1 Healthy Device or device component is healthy.
2 UnHealthy Device or device component is not healthy.

SubscriptionPlan.status

The table below displays the various UserPlanStatusEnum values and their corresponding descriptions.

Value Key Description
1 Active User device protection plan is active.
2 Terminated User device protection plan is terminated.
3 Expired User device protection plan is expired.
4 Completed User device protection plan is completed.
5 Pending User device protection plan is Pending.

DeviceInfoData.deviceHealthCheckStatus

The table below displays the various DeviceHealthCheckStatusEnum values and their corresponding descriptions. It denotes the various phases a device health check of a device can be in.

Value Key Description
1 BackCamera Device health check is currently on the back camera phase.
2 FrontCamera Device health check is currently on the front camera phase.
3 ScreenSensor Device health check is currently on the screen sensor phase.
4 IMEIScanQRCode User is currently on the IMEI/Glass check.
5 IMEIPendingMediaUpload User has scanned the QrCode displayed on the screen and the video recording website has loaded.
6 AwaitingResult User has completed all device health check phases and is currently awaitng device health check result.
7 Failed User's device failed the device health check.
8 Passed User's device passed the device health check.

ConfirmOtpPayload.deviceType

The table below displays the various DeviceTypeEnum values and their corresponding descriptions. It denotes the various device types scrella can cover.

Value Key Description
1 Phone The device is a phone.
2 Tablet The devie is a tablet.
3 POS The device is a POS terminal
4 Laptop The device is a laptop
5 Desktop The device is a desktop screen, the device can also be an All-In-One PC.

PlanData.type

The table below displays the various PlanTypeEnum values and their corresponding descriptions.

Value Key Description
1 Fixed This denotes device protection plans where users pay a fixed premium to get fixed cover limit.
2 DDV This denotes device protection plans where users have to pay some percentage of their Declared Device Value (DDV) as premium and get more percentage of the DDV as cover. Eg - Users can pay 10% of their DDV to get 50% as cover limit

PlanData.status

The table below displays the various PlanStatusEnum values and their corresponding descriptions.

Value Key Description
1 Active Device protection plan is active
2 InActive Device protection plan is inactive. Note: Scrella SDK will not return inactive plans. However, it is best to check and filter out inactive plans.

ClaimData.status, ClaimDetails.status

The table below displays the various ClaimStatusEnum values and their corresponding descriptions.

Value Key Description
0 Pending Claim is yet to be picked up and attended to.
1 Accepted Claim has been accepted and assigned to a repair vendor
2 InReview Repair vendor has accessed the damage and have submitted a repair invoice for approval.
3 InRepair Repair invoice has been approved and repair vendor have started working on the phone. At this point, the user's policy is terminated.
4 RepairCompleted Repair vendor is done with fixing the phone.
5 Closed Claim has successfully completed it cycle and has been closed.
6 Declined Claim was declined.
7 PendingAuthorization Repair invoice requires further authorization.

ClaimData.issue, ClaimDetails.issue

The table below displays the various PlanStatusEnum values and their corresponding descriptions.

Value Key Description
1 ScreenDamage User's device screen is damaged (sensor and/or glass).
2 LiquidSpill Liquid accidentally spilled into the user's device.
3 PhysicalDamage User's device is physically (cosmetic) damaged.
4 TheftLoss User lost their device or user's device is stolen

TerminatePlanPayload.reason

The table below displays the various TerminateReasonEnum values and their corresponding descriptions.

Value Key Text Description
1 NotInterested Not interested anymore User is no longer interested in the plan.
2 CannotAffordIt Can't afford it User is no longer able to afford the plan.
3 PoorExperience Had a poor experience User had a poor experience with the plan.
4 DoNotLikeIt I don't like it User does not like the plan.
5 Others Others User has other reasons for terminating the plan.