Quick start ~ 5min

Welcome to the React Native Ramp documentation !

This page will help you setup your app in less than 5 minutes.

This SDK is written in TypeScript, hance everything is fully typed by design.

TODO: 3 minutes video : embeded

Create a Ramp application

Login with SSO or create email account
First create an account into React Native Ramp dashboard. You can either use any email adress or SSO with Google or Github.
Create a new Ramp application
Navigate to the React Native Ramp applications page, press Create new application, and type a name for your application.
☝️ You don't need to specify any environment suffix in this application name, as applications can handle multiple environments
Once your application created, you will be able to access its applicationId, that will be used in the next steps of this Quick Start.
Two environments are automaticaly created: beta and prod.
Manage these environments as you wish. as they are only generated for conveniency.
- Use them like this,
- Remove one or both of them,
- Add any other another environment you like, such as staging for example.
Any of this environment is associated with an environmentId, that will be used in the next steps of this Quick Start.

Installing the mobile SDK

0. Create a new React Native application if needed

If you currently don't have any react-native application, start by setting up your project following the instructions on the React Native documentation website

Using Expo ?

react-native-ramp is designed to work with React Native CLI projects. Unfortunatly Expo projects are not supported.

1. Install React Native Ramp library in your project

You can either use Yarn:

yarn add react-native-ramp

or npm:

npm install --save react-native-ramp

2. Configure your Android project

Modify your AndroidManifest.xml file to add these values :

AndroidManifest.xml
<manifest ... >

    ...

    <application ... >
    
    <!-- ADD THE 3 FOLLOWING LINES -->
    <meta-data android:name="com.reactnativeramp.ApplicationId" android:value="YourApplicationId"/>
    <meta-data android:name="com.reactnativeramp.EnvironmentId" android:value="YourEnvironmentId"/>
    <meta-data android:name="com.reactnativeramp.Apikey" android:value="YourAPIKey"/>
    
    ...

    </application>
</manifest>

Where :

com.reactnativeramp.ApplicationId is the applicationId of the React Native Ramp application you just created,
com.reactnativeramp.EnvironmentId is the environmentId of the environment you want to target in the application,
com.reactnativeramp.Apikey is an SDK API key assocaiated to this environment.

tip

In this example we are configuring our app for a single environment. For more information about how to manage multiple environments variables on Android, go to the How to setup and manage multiple environments on a React Native application guide page.

Open your MainApplication.java file to modify these 2 functions of the ReactNativeHost :

public boolean getUseDeveloperSupport();

and

protected String getJSBundleFile();

like in this sample file :

MainApplication.java
// ADD THIS IMPORT
import com.ramp.RampPackage;

...

public class MainApplication extends Application implements ReactApplication {
    ...
    
    private final ReactNativeHost mReactNativeHost = new ReactNativeHost(this) {
        ...

        @Override
        public boolean getUseDeveloperSupport() {
            // REPLACE THIS LINE
            return RampPackage.getUseDeveloperSupport(MainApplication.this);
        }

        @Override
        protected String getJSBundleFile() {
            // REPLACE THIS LINE
            return RampPackage.getJSBundleFile(MainApplication.this);
        }

        ...
    };

    ...
}

3. Configure your iOS project

Modify your Info.plist file to add these values :
Info.plist
```
<plist>
<dict>

    ...

    // ADD THIS 3 KEY/VALUE PAIRS
    <key>RampApplicationId</key>
    <string>YourApplicationId</string>
    <key>RampEnvironmentId</key>
    <string>YourEnvironmentId</string>
    <key>RampApikey</key>
    <string>YourAPIKey</string>
</dict>
</plist>
```
Where :
- RampApplicationId is the applicationId of the React Native Ramp application you just created,
- RampEnvironmentId is the environmentId of the environment you want to target in the application,
- RampApikey is an SDK API key associated to this environment.

tip

In this example we are configuring our app for a single environment. For more information about how to manage multiple environments variables on iOS, go to the How to setup and manage multiple environments on a React Native application guide page.

Open your AppDelegate.m file to modify this function :

- (NSURL *)sourceURLForBridge:(RCTBridge *)bridge;

like in this sample file :

AppDelegate.m
// ADD THIS IMPORT
#import <RampSDK.h>

...

@implementation AppDelegate

...

- (NSURL *)sourceURLForBridge:(RCTBridge *)bridge
{
    // ADD THIS LINE
    return [RampSDK sourceURLForBridge:bridge];
}

...

@end

4. Configure the React Native project

Update your root component by

Configuring the automatic updates,
Adding the React Native Ramp menu has an Hight Order Component, allowing you to manage manually updates in 2 lines of codes.

import React from 'react';
import { RampMenuHOC, RampSDK } from 'react-native-ramp';

...

RampSDK.initAutomaticUpdate({
    updateCheckMode: 'ON_FOREGROUND',
    updateCheckInterval: 'ALWAYS',
    updateMode: 'ON_FOREGROUND',
});

const AppWithRampMenu = () => {
    return (
        <RampMenuHOC>
            <App />
        </RampMenuHOC>
    );
};

export default AppWithRampMenu;

tip

There is many other built-in method to manage automatic updates. To learn more about these you can go to the Deep dive into the SDK documentation page.

tip

The quickest way to use the built-in React Native Ramp menu is has a Hight Order Component, but it can also be used has a any other component, or you can recreate one from scratch using the SDK. To learn more about it go to the Understand the SDK built-in menu documentation page.

example application

An already configured example application is available here on GitHub.

Installing and setting up the CLI

Installing the CLI

There is two different ways of using the CLI

Install the React Native Ramp CLI package in your project. You can either use Yarn:
```
yarn add react-native-ramp-cli
```
or npm:
```
npm install --save react-native-ramp
```
Install the React Native Ramp CLI globally :
```
npm install -g react-native-ramp-cli
```

Provisionning the CLI with an API key

The setup of the CLI is mostly automatic, during the provisioning phase, the CLI will automatically generate an API key for you. This API key will be associated to a specific application and a specific environment.

tip

Alternatively you can manually create a CLI API key throught the web dashboard. For more information about this manual procedure go to the Managing API keys documentation page.

Start the configuration by running the following command:
```
ramp-cli apikeys add
```
You'll be ask if rather setup the API key automatically via login, or manually by entering the informations related to an already created API key.
Choose automatically.
The login process will take place in the browser, where you wil be invited to login to the previously created account, loggin you automatically into your terminal.
☝️ If you are setting up the CLI throught a CI environment, choose the manual entry to fill up your application and API key informations without logging in into a browser. For more information about this manual procedure go to the CLI API documentation page.
Once the login process completed, select which application you whish to configure.
Next select on which environment you whish to create the API key.
Finally, select Create a new API key, and choose a name for this API key. It will be available and manageable from the web dashboard.
☝️ Alternatively, you can choose a previously created API key in the list that has been fetched from your web dashboard. For more information about this manual procedure go to the Managing API keys documentation page.
Your CLI is now provisionned !

Try it out

The SDK is now installed in your application, and the CLI is ready to use !

Here are the last few steps to try your newly installed library:

Build this new version of your application and send it to your simulator, device, or private appstore,
Do some modifications on your React-Native codebase,
Release these modifications throught React Native Ramp by running the following command:
```
ramp-cli release ${platform}
    --app ${yourApplicationId}
    --env ${yourEnvironmentId}
    --target ${applicationTargetedVersion} # eg: "0.4" or "1.2.3"
    --dist "my-feature"
    --label 'second fix'
```
Here some details about these arguments:
- platform : the targeted mobile platform, valid values are android, ios or mobile
- --app (-a) : the React Native Ramp application you want to target,
- --env (-e) : the environment you want to target on this application,
- --target (-t) : the native version of your application you want to target, usualy following the semver specification,
  🎯 To get an example of a native application version system or to get more informations about version targeting, go to the How to setup and handle a efficient versionning system on a React Native application guide page.
- --dist (-d)(optional) : the distribution you want to send your bundle to, this parameter is optional and is setted to the value main by default.
  🔀 Distributions is a powerful way of managing multiple feature developments at the same time on the same installed application, go to the Distributions and updates Workflows documentation page to learn more about it.
- --label (-l)(optional) : an optional label that will shortly describe this specific bundle release.
tip
Some of these releases arguments are going to be the same over time, or are going to change only when the deploy environment change, therefore they can be configured once in the .ramprc.json config file. For more information go to the CLI configuration documentation page.
Launch your newly built application
To test the automatic updates :
☝️ In order to try an automatic update, your bundle needs to be send on the main distribution, which is the default one if you did not specify any.
- Send your application to the background,
- Get your application back to foreground,
  - As the updateCheckMode is configured with the ON_FOREGROUND value, the SDK will check for an update everytime your application come back from the background and download it silently, ready to be installed,
  - You could have to wait several seconds/minutes if your connectivity is low and/or your bundle is heavy.
- Send your application to the background,
- Get your application back to foreground,
  - As the updateMode is also configured with the ON_FOREGROUND value, the update will be installed the next time your application come back from the background.
To manage updates manually (on the main distribution and all others) :
☝️ Only the bundles targeting the same version as your running application will be displayed.
- Open the React Native Ramp menu by pressing the ⚙️ button,
- You can now refresh, install, and uninstall your bundles.

tip

The way you display and hide the React Native Ramp menu can be fully configured, and the default buttons visible at the application startup can also be hidden. To learn more about it go to the Understand the SDK built-in menu documentation page.

Quick start ~ 5min

Create a Ramp application​

Installing the mobile SDK​

0. Create a new React Native application if needed​

1. Install React Native Ramp library in your project​

2. Configure your Android project​

3. Configure your iOS project​

4. Configure the React Native project​

example application​

Installing and setting up the CLI​

Installing the CLI​

Provisionning the CLI with an API key​

Try it out​