React Native Integration
Integrate smallcase Gateway React Native SDK to allow your users to transact in stocks, ETFs & smallcases, and much more
Step 1 - Install and Configure
Gateway React-Native SDK is available on npm. To install the SDK:
- Add the the javascript module using the preferred package manager.
yarn add react-native-smallcase-gateway
npm install react-native-smallcase-gateway
- The library exports all its methods with one default import. Import it using
import SmallcaseGateway from "react-native-smallcase-gateway";
A. Android
- Add these lines to your project level
build.gradle
allprojects {
repositories {
// .. your existing repositories
// Starting from version 2.3.0 all versions of the sdk are now hosted on a public repository
maven {
url "https://artifactory.smallcase.com/artifactory/SCGateway"
}
// Only for versions < 2.3.0
maven {
url "https://artifactory.smallcase.com/artifactory/gradle-dev-local"
credentials {
username "react_native_user"
password "reactNativeUser123"
}
}
}
}
- Add these lines in
AndroidManifest.xml
in the main<application />
tag
<activity android:name="com.smallcase.gateway.screens.transaction.activity.TransactionProcessActivity"
android:exported="true">
<intent-filter>
<action android:name="android.intent.action.VIEW" />
<category android:name="android.intent.category.BROWSABLE" />
<category android:name="android.intent.category.DEFAULT" />
<data
android:host="<YOUR_GATEWAY_NAME>"
android:scheme="scgateway"
/>
</intent-filter>
</activity>
<activity android:name="com.smallcase.gateway.screens.common.RedirectActivity"
android:exported="true">
<intent-filter>
<action android:name="android.intent.action.VIEW" />
<category android:name="android.intent.category.BROWSABLE" />
<category android:name="android.intent.category.DEFAULT" />
<data
android:host="<YOUR_GATEWAY_NAME>"
android:scheme="scgatewayredirect"
/>
</intent-filter>
</activity>
Replace "{YOUR_HOST_NAME}" with unique host name which is given to every integration partners.
Note
If your app targets Android 12 or higher you must explicitly declare the android:exported attribute for these activities. If an activity doesn't have an explicitly-declared value for android:exported, your app can't be installed on a device that runs Android 12 or higher.
B. iOS
smallcase Gateway iOS SDK is available as a private cocoa pod dependency.
add following code to your Podfile and run pod install
within the directory containing the Podfile.
# default source for all other pods
source 'https://cdn.cocoapods.org'
# private podspec for smallcase (only for versions < 2.3.0)
source 'https://github.com/smallcase/cocoapodspecs.git'
# update the ios version if it was previously below 11.0
platform :ios, '11.0'
Note
Running pod update after adding a source will trigger a clone of the the source repo. This operation might take time when
pod update
is run for the first time. Subsequent updates will be faster.
Step 2- Environment Setup
To start using gateway setup the gateway SDK with the desired configuration by calling setConfigEnvironment method.
await SmallcaseGateway.setConfigEnvironment({
isLeprechaun: true,
isAmoEnabled: true,
gatewayName: "<YOUR_GATEWAY_NAME>",
// `environmentName` should always be PROD, regardless of your environment
environmentName: SmallcaseGateway.ENV.PROD,
brokerList: [],
});
Params :
- environment (required): This defines the Url environment to which all the gateway apis would point to Possible values - SmallcaseGateway.ENV.PROD
- gateway (required): This is a unique name given to every gateway consumer
Eg : moneycontrol - leprachaun_mode (required): For Testing purpose only. Default value is false
- isAmoEnabled (required): To control after-market order placement.
- brokers (optional): If you want to support only certain brokers, default all brokers are shown if empty list is passed
Possible values - aliceblue, angelbroking, axis, dhan, edelweiss, fisdom, fivepaisa, fundzbazar, groww, hdfc, icici, iifl, kite, kotak, motilal, trustline & upstox
Note
Call setConfigEnvironment every time there is any change in the setup.
setConfigEnvironment must be the first method to be fired.If setup is not called all other methods will not work.
Step 3- Initialise user session
User initialization starts a session between the distributor and the gateway. Whenever there is a change in user session, this method needs to be triggered.
const initGatewaySession = useCallback((sdkToken) => {
SmallcaseGateway.init(sdkToken)
.then((initResp) => {
// successfuly initialised gateway session
console.log(initResp);
})
.catch((err) => {
// error initialising gateway session:
// confirm that `sdkToken` has valid payload and is signed with correct secret
console.log(err.userInfo);
});
}, []);
Params :
authToken (required): JWT with the information of user signed using a shared secret between smallcase API and gateway backend. Learn more about using JWT
Call order
It is important to call
setConfigEnvironment
beforeinit
. Either use Promise chaining or the await syntax to ensure init is called after setConfigEnvironment.Subsequent transactions will only go through after init runs successfully.
Step 4- Triggering SDK Method
A. For transactional flows
Transactional flows are those user journeys where interaction with their broker is required to complete the flow. For example - placing stocks / smallcase order, importing user holdings, connecting broker account to your app.
smallcase Gateway assigns a unique transactionId for each such user intent. The transactionId is a short-lived identifier that represents a single user interaction session.
i - Create transactionId
The transactionId can be created by making a server-to-server request to create transactionId API with relevant order config. The API call must be made from your backend (it is critical that secrets not be used on the app).
So whenever your user wants to perform transaction action, your app must call your backed with relevant order config, which in turn will hit smallcase Gateway's create transactionId API and respond back with transactionId.
Create transactionId API reference -
ii - Call triggerTransaction SDK method
To start the actual transactional flow, call the triggerTransaction method.
const startTransaction = useCallback((transactionId) => {
SmallcaseGateway.triggerTransaction(transactionId)
.then((txnResponse) => {
/*
* Transaction intent fulfilled.
* Response structure & example - https://developers.gateway.smallcase.com/docs/transaction-response
*/
console.log("received response:", txnResponse);
})
.catch((err) => {
/*
* Gateway flow ended before transaction intent fulfilment.
* Possible errors - https://developers.gateway.smallcase.com/docs/transaction-errors
*/
console.log("received error:", err.userInfo);
});
}, []);
Params :
transactionId (required): a unique string that you received from backend in the previous step.
B. For Non-transactional flows
i - Call relevant SDK method
Description | SDK Method |
---|---|
Broker account opening | triggerLeadGen |
Logout from smallcase platform | logoutUser |
(More details in Non-transactional flow section)
Step 4 - Save order response
Order response is shared in the onSucess()
block of the triggerTransaction
method as well as over API webhooks
Check response structure here
In case the transaction is not placed with the broker, any error is available in the err.userInfo
block
A list of transaction errors is available here
Non-transactional flows
Note
In order to use any of the following methods, the gateway session should be initialized with relevant user data.
Broker Account Opening
To trigger account opening flow call triggerLeadGen
method.
SmallcaseGateway.triggerLeadGen(userInfo) => void
Params
userInfo (optional): object to pre-fill some details in the signup form.
Supported keys -
name
- name of the useremail
- email of the usercontact
- contact number of the user
And for all relevant keys passed to the triggerLeadGen
method, the SDK will pre-populate relevant user data in the signup flow, ensuring a smooth user experience.
Logout from smallcase platform
This method is particularly useful when your users want to switch accounts for the same broker. When triggered, this method will make sure that the user gets logged out from the smallcase platform. So that the next time user interacts with smallcase Gateway, they will be asked to log in again.
Note: This flow is only available for connected users.
try {
const userLogout = await SmallcaseGateway.logoutUser();
} catch (err) {
//Error callback
console.log("received error:", err.userInfo);
}
Show Orders
This will display a list of all the orders that a user recently placed. This includes pending, successful, and failed orders.
try {
const showOrdersRes = await SmallcaseGateway.showOrders();
} catch (err) {
//Error callback
console.log("received error:", err.userInfo);
}
Updated 8 months ago