yimba_sdk 1.3.1

Yimba Flutter SDK

Yimba Flutter SDK

Installation

dart pub add yimba_sdk

Usage

Import the library

import 'package:yimba_sdk/yimba_sdk.dart';

Obtaining an Access Token

To integrate this SDK into your application, you will need to have an account set up with Yimba and obtain a client ID. The client ID should be embedded within your application as it is a required parameter for most of the methods.

You will need to use this account to obtain a bearer token using the following method to utilise the methods within the SDK. This token should be saved within your application and sent in the header for all subsequent authenticated API requests.

Future<String> getAccessToken(
    String email,
    String password
);

/// Example usage:
String accessToken = await getAccessToken("[e-mail]", "123!456");

Registering a new card

Upon user registration, you are required to register a new card for the user before any of the authenticated methods can be used.

The card identifier should be saved persistently, such as in a 'SharedPrefUtils' library or a custom endpoint to save the card identifier to the user, it should never be re-registered for the same user. Otherwise, the card identifier will be lost and the user will need to register a new card, meaning they lose their data.

Future<String> registerCard(
    String bearerToken,
    String clientId,
    String bin,
    ImageTypeModel defaultImage,
    String providerReferenceId,
);

// Example usage:
String bearerToken = 'your_bearer_token';
String clientId = 'your_client_id';
String bin = 'your_bin';
ImageTypeModel defaultImage = ImageTypeModel(
    imageName: 'DefaultCard',
    imageType: "URL",
    imageData: 'https://s3.eu-west-2.amazonaws.com/images/card.png'
    ),
String providerReferenceId = 'your_provider_reference_id';

String registerCard = await registerCard(
    bearerToken,
    clientId,
    bin,
    defaultImage,
    providerReferenceId,
  );

Authenticated methods

Once you have obtained an access token and registered a card, you can now use the following methods:

Future<List<DesignHistoryResponse>> getDesignHistory(
  String bearerToken,
  String clientId,
  String cardIdentifier
)

Future<List<YimbaDesignCategoryModel>> getDesignCategories(
    String bearerToken,
    String clientId
)

Future<CardDesignResponse> getCardDesign(
    String bearerToken,
    String clientId,
    String cardIdentifier
)

Future<String> getDesignUrl(
    String bearerToken,
    String designId
)

Future<ProgrammeResponse> getProgrammeId(
    String bearerToken,
    String cardIdentifier
)


Future<List<ContentResponse>> getContent(
  String programmeId,
)

Future<List<BrandConfigurationsResponse>> getBrandConfigurations(int programmeId)

Component Kit

The library also provides Flutter components to simplify integration with the SDK. These components handle the screens and flow, eliminating the need to directly use the authenticated methods mentioned above.

To use these components, you still need to obtain a valid access token and register a card as a user, following the steps mentioned above. Pass these parameters to the SDK components.

The Flutter components also rely on the theme context of the base application that implements the SDK. Make sure that the styles used within these components have been set in your base theme.

To see how to integrate the component kit, you can refer to the example host app. It demonstrates the implementation of the SDK in a real-world scenario.

Available components:

YimbaCard

The YimbaCard widget is used to display the currently selected card design for the card identifier that resembles a credit card.

YimbaCard(
    bearerToken: "your_bearer_token",
    clientId: "your_client_id",
    cardIdentifier: "the_card_identifier",
),

YimbaDesigns

The YimbaDesigns widget is used to provide the screens and flows for customizing the card design.

This component handles the user flow for customization, including displaying design categories, card design history, promoted content, and previewing of selected YimbaCard to be set.

Once a new design has been selected and set, it will automatically return back to the previous screen.

YimbaDesigns(
    bearerToken: "your_bearer_token",
    clientId: "your_client_id",
    cardIdentifier: "the_card_identifier",
),

YimbaContent

The YimbaContent widget is used to provide the screen and flows for displaying the content hub screens.

This component handles web view functionality internally when navigating to a content item.

Note that unlike the other widgets, the YimbaContent widget needs to render its own scaffold due to the coloring of the app bar when changing through brands. Therefore, do not render this widget inside a scaffold. Instead, simply render the component onto the screen as the top level Widget.

YimbaContent(
    bearerToken: "your_bearer_token",
    clientId: "your_client_id",
    cardIdentifier: "the_card_identifier",
),

Theming

The styling used within the widgets of the component kit relies on the ThemeData of the consumer app for text and colors.

Here are the styles used within the SDK:

• Primary Color: Used as the background color for the button in the YimbaCardPreview widget (used in YimbaDesigns flow) and as the background color for the button in promoted content carousels.

• highlightColor: Used for the text color on the button in the YimbaCardPreview widget (used in YimbaDesigns flow), as the background color on the currently selected filter item in YimbaDesigns, and as the background color for bottom level content and the text color for top level content in promoted content carousels.

• hintColor: Used as a darker primary color background for the background color of filter items that are not currently selected in YimbaDesigns, as the border color for the selected filter, as the text color for the design category names in YimbaDesigns, and as the background color for top level content in promoted content carousels.

• shadowColor: Used as the text color in promoted content carousels for the text color in bottom level carousels.

• textTheme.labelLarge: Used as the text style for the button in YimbaCardPreview widget (used in YimbaDesigns flow).

example usage:

var appTheme = ThemeData(
  colorScheme: const ColorScheme.light(
    primary: Color.fromRGBO(0, 169, 206, 1),
  ),
  shadowColor: Colors.black,
  hintColor: const Color.fromRGBO(0, 129, 157, 1),
  highlightColor: Colors.white,
  textTheme: const TextTheme(
    labelLarge: TextStyle(fontWeight: FontWeight.normal, fontSize: 22),
  ),
);

Licence

// todo