Carbon Calculator SDK

Version 1.0.3

Carbon Calculator SDK Overview

1.1. What is Carbon Calculator SDK?

1.2. How Carbon Calculator SDK works?

1.3. Versioning and backward compatibility
Technical overview

2.1. Basic information

2.2. Basic configuration

2.3. Carbon Calculator SDK Setup

2.4. Error handling
Carbon Calculator Service

3.1. getTransactionsFootprints
Document changelog

4.1 Version 1.0.0

4.2 Version 1.0.2

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.

    
  

    
repositories {  
	maven { 
		credentials { 
			username "<enter_username_here>" 
			password "<enter_password_here>" 
		} 
		 url "https://artifactory.upaid.pl/artifactory/libs-release-local/"
	}
}

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.
Debug version is ended with appendix "-debug" in version name.
Samples below.

For release version, used on production environment in application uploaded to Google Play:

    
  

    
dependencies {  
	implementation 'com.verestro.sdk:carbon-calculator:{version}'
}

For debugging purposes:

    
  

    
dependencies {  
	implementation 'com.verestro.sdk:carbon-calculator-dev:{version}-debug'
}

2.2.1 Source code obfuscation and optimization

As SDK is written in Kotlin language we recommend to add following code to gradle configuration:

    
  

    
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:

    
  

    
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

    
  

    
fun init(configuration: Configuration) {  
	CarbonCalculatorCoroutineApi.init(configuration)
}

CarbonCalculatorStdApi

    
  

    
fun init(configuration: Configuration) {  
	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

    
  

    
Asynchronous. Online.  
  
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.