Carbon Calculator SDK
Version 1.0.12
Table of Contents
Carbon Calculator SDK Overview
1.1. What is Carbon Calculator SDK?
-
2.1. Basic information
2.2. Basic configuration
2.3. Carbon Calculator SDK Setup
2.4. Error handling
-
4.1 Version 1.0.0
4.2 Version 1.0.2
4.3 Version 1.0.3
4.4 Version 1.0.4
4.5 Version 1.0.5
4.6 Version 1.0.6
4.7 Version 1.0.7
4.8 Version 1.0.8
4.9 Version 1.0.9
4.10 Version 1.0.10
4.11 Version 1.0.11
4.12 Version 1.0.12
1. Carbon Calculator SDK Overview
1.1. What is Carbon Calculator SDK?
The Carbon Calculator SDK is a module dedicated for previewing the estimated carbon footprint of transactions.
1.2. How Carbon Calculator SDK works?
In order to incorporate this SDK into your app, see Basic configuration
1.3. Versioning and backward compatibility
SDK is based on semantic versioning.
For example: 1.0.0 ( MAJOR.MINOR.PATCH )
- Major version compatibility-breaking changes in SDK public APIs.
It is mandatory to update application code, to use SDK, when this is incremented. - Minor version tracks new, not compatibility-breaking changes in public API of SDK.
It is optional to update application code, when this digit is incremented. - Patch version tracks internal changes in SDK.
No updates in application code are necessary to update to version, which has this number incremented.
Changes not breaking compatibility:
- adding new optional interface to SDK setup
- adding new method to any domain
- adding new enum value to input or output
- adding new field in input or output model
2. Technical overview
This section describes basic information about Carbon Calculator SDK setup and available methods.
2.1. Basic information
2.1.1 Facade
Facade is entry point to communication with Carbon Calculator SDK.
2.1.2 Multiple facade types
Carbon Calculator SDK provides two public API's with same functionalities, the API's are:
- CarbonCalculatorCoroutineService for projects which uses Kotlin programming language and Coroutines.
- CarbonCalculatorStdService for projects which uses Kotlin or Java programming language and standard Callback.
The difference between the API's is a way of providing data to SDK methods and getting the results from them.
Input and output as an data models are the same.
This documentation presents I/O types in a Kotlin way as it's easier to mark nullable fields (as question mark).
2.1.3 Method structure
Every method description has same structure.
Execution type:
- Asynchronous - operation could take more time and method is called on thread different than main.
The result of execution is provided in callback (described below). - Synchronous - result of operation is provided as method return type.
Method type:
- Online - operation requires Internet connection.
- Offline - operation can be called without Internet connection.
Input Input parameters with name, type and description.
Output Result delivered by standard Callback with data or result is suspended until the Coroutine completes <Multiple facade types>.
2.2 Basic configuration
2.2.1 Min SDK Version
The minSdkVersion must be at least 23 (Android 6.0).
2.2.2 Artifactory
SDK is available on Verestro maven repository and can be configured in project using Gradle build system.
Username and password are provided by Verestro.
maven {
credentials {
username "<enter_username_here>"
password "<enter_password_here>"
}
url "https://artifactory.verestro.com/artifactory/android-release/"
}} ```
#### 2.2.3 SDKs version
Carbon Calculator SDK is available in two versions: debug and release.
The difference between version is debug allows to use application with debugger connected.
Samples below.
For release version, used on production environment in application uploaded to Google Play:
```gradle dependencies {
implementation 'com.verestro.sdk:carbon-calculator:{version}'
} ```
For debugging purposes:
```gradle dependencies {
implementation 'com.verestro.sdk:carbon-calculator:debug-{version}'
} ```
#### 2.2.1 Source code obfuscation and optimization
As SDK is written in Kotlin language we recommend to add following code to gradle configuration:
```gradle android { ...
kotlinOptions {
freeCompilerArgs = [
'-Xno-param-assertions',
'-Xno-call-assertions',
'-Xno-receiver-assertions'
]
}
packagingOptions { exclude '/kotlin_metadata/**' } ...
} ```
Then use newest tools for code shrinking, optimization and obfuscation from Google by enabling R8 instead Proguard in gradle.properties file:
```gradle android.enableR8=true ```
### 2.3 Carbon Calculator SDK Setup
Available configuration methods:
- CarbonCalculatorCoroutineApi.init(configuration: Configuration)
- CarbonCalculatorStdApi.init(configuration: Configuration)
#### 2.3.1 Input
| Parameter | Type | Description | |------------------|-----------------|------------------------| | applicationId | String | Application Id | | url | String | API hostname URL |
| certificateHashes| List \<String> | API hostname Pin SHA256|
#### 2.3.2 Sample
**`CarbonCalculatorCoroutineApi`**
```kotlin fun init(configuration: Configuration) {
CarbonCalculatorCoroutineApi.init(configuration)
} CarbonCalculatorStdApi
CarbonCalculatorStdApi.init(configuration)
} 2.4 Error handling
SDK returns errors by CarbonCalculatorException, which could be catched by application and shown on UI with detailed message.
Table below describes general exception types.
CarbonCalculatorException
| Exception | Parameters | Description | |-------------------------------------|----------------------------|------------------------------------------------------------------------------| | BadRequestException | | Server cannot process request. Example reasons: * invalid payload. | | TransactionsLimitExceededException | | Too many transactions given in request. Mastercard limit is 5000. | | InvalidAuthorizationHeaderException | | Invalid authorization header. | | MissingAuthorizationHeaderException | | Missing authorization header. | | InvalidAccessTokenException | | Requested access token is invalid. | | AccessDeniedException | | Invalid or missing Application-Id header. | | ExternalServiceUnavailableException | | System is heavily dependant of external service which can block proper work. | | NoCertificatePinningException | | No certificate pinning. | | SessionExpiredException | | Session expired. | | RequestCancelledException | | Request was canceled. | | TechnicalException | message: String? | Technical exception. | | UnknownErrorException | message: String? | An unknown error occurred. | | UnknownErrorStatusException | status: String? | An unknown error occurred. | | HttpApiException | code: Int, message: String?| HTTP API exception. |
3 Carbon Calculator Service
3.1 getTransactionsFootprints
This method obtains carbon footprint for given transactions. ```
#### 3.1.1 Input
**`GetTransactionsFootprintsData`**
| Parameter | Type | Description | |--------------|--------------------------|-------------------------------| | transactions | List \<TransactionModel> | List of transactions. |
**`TransactionModel`**
| Parameter | Type | Description | |---------------|------------------------|---------------------------------------------------------------------------------------------------------| | transactionId | String | Transaction identifier. |
| mcc | String | Merchant category code of transaction that uniquely defines a merchant business. |
| amount | AmountModel | Transaction amount with currency. |
| cardType | CardType? | Optional. Brand type of the payment card through which transaction done. One of: [MASTERCARD], [OTHER]. |
**`AmountModel`**
| Parameter | Type | Description | |--------------|------------------------|--------------------------------| | value | Float | Transaction amount. | | currencyCode | String | Currency code as per ISO 4217. |
**`CardType`**
| Type | Description | |--------------|----------------------------------| | MASTERCARD | Mastercard card brand | | OTHER | Card brand other than Mastercard |
#### 3.1.2 Output
##### 3.1.2.1 Success
``` Success callback with GetTransactionsFootprintsResult model. ```
**`GetTransactionsFootprintsResult`**
| Parameter | Type | Description | |------------------------|-----------------------------------|---------------------------------| | transactionsFootprints | List \<TransactionFootprintModel> | List of transaction footprints. |
**`TransactionModel`**
| Parameter | Type | Description | |------------------------|----------------|---------------------------------------------------------------------------------------------------------------------| | transactionId | String | Transaction identifier. |
| mcc | String | Merchant category code of transaction that uniquely defines a merchant business. |
| carbonEmissionInGrams | Float? | Optional. The transaction's CO2 emission in grams. Possible negative values (in case of Refund Transaction). |
| carbonEmissionInOunces | Float? | Optional. The transaction's CO2 emission in ounces. |
| cardType | CardType? | Deprecated. Optional. Brand type of the payment card through which transaction done. One of: [MASTERCARD], [OTHER]. |
| cardTypeValue | CardTypeValue? | Optional. Value class encapsulating sample type as a [value] String field |
**`CardType (deprecated)`**
| Type | Description | |--------------|----------------------------------| | MASTERCARD | Mastercard card brand | | OTHER | Card brand other than Mastercard |
**`CardTypeValue`**
| Value | Description | Supporting const |
|-------|----------------------------------|--------------------------|
| MA | Mastercard card brand | CardTypeValue.MASTERCARD |
| OTH | Card brand other than Mastercard | CardTypeValue.OTHER |
##### 3.1.2.2 Failure
``` Failure callback with throwable. ```
#### 3.1.3 Sample
**`Standard Callback`**
```kotlin fun getTransactionsFootprints(getTransactionsFootprintsData: GetTransactionsFootprintsData) {
CarbonCalculatorCoroutineApi
.carbonCalculatorStdService .getTransactionsFootprints( getTransactionsFootprintsData = getTransactionsFootprintsData, callback = object : ApiCallback<GetTransactionsFootprintsData> {
override fun onSuccess(response: GetTransactionsFootprintsData) { // handle success }
override fun onFailure(error: Throwable) { // handle error } } )
} Kotlin Coroutines
getTransactionsFootprintsData: GetTransactionsFootprintsData ): GetTransactionsFootprintsResult =
CarbonCalculatorCoroutineApi
.carbonCalculatorCoroutineService
.getTransactionsFootprints(getTransactionsFootprintsData = getTransactionsFootprintsData) ``` ___
## 4. Document changelog
### 4.1. Version 1.0.0
- Created Carbon Calculator SDK.
### 4.2. Version 1.0.2
- Added new type of exception - TransactionsLimitExceededException.
### 4.3. Version 1.0.3
- Disables pinning and obfuscation for debug.
### 4.4. Version 1.0.4
- Updated koin to version 3.5.3.
- Updated java to 17.
- Updated compile and target android version.
### 4.5. Version 1.0.5
- Marked `cardType` field in SDK result model with @Deprecated.
- Added corresponding value class field `cardTypeValue` for deprecated field.
### 4.6 Version 1.0.6
- Improved SDKs deploying.
- ### 4.7. Version 1.0.7
- Internal changes have been introduced to improve build process.
### 4.8 Version 1.0.8
- Update koin to version 4.0.4
- Update java to 21
- Update compile and target android version
### 4.9 Version 1.0.9
- Internal changes improving SDK delivery process.
### 4.10 Version 1.0.10
- Internal. Updates build utilities.
### 4.11 Version 1.0.11
- Internal changes improving SDK.
### 4.12 Version 1.0.12
- Internal changes. Updated supported token handling.