react-native-branch
Advanced tools
Comparing version 0.0.12 to 0.1.0
{ | ||
"name": "react-native-branch", | ||
"version": "0.0.12", | ||
"description": "Native Wrapper around Branch Metrics native SDKs", | ||
"main": "index.js", | ||
"version": "0.1.0", | ||
"description": "Branch Metrics React Native SDK", | ||
"main": "src/index.js", | ||
"files": ["src", "docs", "android", "RNBranch", "react-native-branch.podspec"], | ||
"scripts": { | ||
"test": "echo \"Error: no test specified\" && exit 1" | ||
"test": "ava" | ||
}, | ||
"ava": { | ||
"require": [ | ||
"babel-register", | ||
"babel-polyfill", | ||
"react-native-mock/mock.js", | ||
"./test/helpers/RNBranch.mock.js" | ||
], | ||
"babel": "inherit" | ||
}, | ||
"babel": { | ||
"ignore": false, | ||
"presets": [ | ||
"react-native" | ||
] | ||
}, | ||
"keywords": [ | ||
@@ -24,8 +40,19 @@ "react-native", | ||
"type": "git", | ||
"url": "git+https://github.com/DispatcherInc/react-native-branch.git" | ||
"url": "git+https://github.com/BranchMetrics/react-native-branch.git" | ||
}, | ||
"bugs": { | ||
"url": "https://github.com/DispatcherInc/react-native-branch/issues" | ||
"url": "https://github.com/BranchMetrics/react-native-branch/issues" | ||
}, | ||
"homepage": "https://github.com/DispatcherInc/react-native-branch#readme" | ||
"homepage": "https://github.com/BranchMetrics/react-native-branch", | ||
"devDependencies": { | ||
"ava": "^0.14.0", | ||
"babel-eslint": "^6.0.4", | ||
"babel-polyfill": "^6.7.4", | ||
"eslint": "^2.7.0", | ||
"eslint-config-rackt": "^1.1.1", | ||
"react": "^0.14.8", | ||
"react-dom": "^0.14.8", | ||
"react-native": "^0.24.1", | ||
"react-native-mock": "0.0.7" | ||
} | ||
} |
290
README.md
@@ -1,187 +0,187 @@ | ||
# react-native-branch | ||
Native Wrapper around Branch Metrics native SDKs. Tested with React Native 0.21.0. | ||
# Branch Metrics React Native SDK Reference | ||
Supports iOS and Android. | ||
This is a repository of our open source React Native SDK. Huge shoutout to our friends at [Dispatcher, Inc.](https://dispatchertrucking.com) for their help in compiling the initial version of this SDK. | ||
## Usage | ||
**v0.1.0** has just been released with **breaking changes**! [[Upgrade Notes]](https://github.com/BranchMetrics/react-native-branch/issues/8) | ||
```js | ||
var branch = require('react-native-branch'); | ||
//Receives the initSession's result as soon as it becomes available | ||
branch.getInitSessionResultPatiently(({params, error}) => { }); | ||
branch.setDebug(); | ||
branch.getLatestReferringParams((params) => { }); | ||
branch.getFirstReferringParams((params) => { }); | ||
branch.setIdentity("Your User's ID"); | ||
branch.userCompletedAction("Purchased Item", {item: 123}); | ||
var shareOptions = {messageHeader: "Check this out!", messageBody: "Check this cool thing out: "}; | ||
var branchUniversalObject = {metadata: {prop1: "test", prop2: "abc"}, canonicalIdentifier: "RNBranchSharedObjectId", contentTitle: "Cool Content!", contentDescription: "Cool Content Description", contentImageUrl: ""}; | ||
var linkProperties = {feature: 'share', channel: 'RNApp'}; | ||
branch.showShareSheet(shareOptions, branchUniversalObject, linkProperties, ({channel, completed, error}) => {}); | ||
branch.logout(); | ||
``` | ||
## Installation | ||
```sh | ||
npm install rnpm -g | ||
npm install --save react-native-branch | ||
rnpm link react-native-branch | ||
cd node_modules/react-native-branch | ||
pod install #Only required for iOS | ||
``` | ||
1. `npm install --save react-native-branch` | ||
2. `rnpm link react-native-branch` **or** link the project [manually](./docs/installation.md#manual-linking) | ||
3. Add `pod 'Branch'` to your ios/Podfile ([details](./docs/installation.md#cocoa-pods)) | ||
4. `cd ios && pod install` | ||
5. Follow the [setup instructions](./docs/setup.md) | ||
### Android | ||
If you are new to react-native or cocoa-pods, read below for more details: | ||
- [Full Installation Instructions](./docs/installation.md) | ||
- [If you already have React in your Podfile](./docs/installation.md#pod-only-installation) | ||
- [If you do not know what a Podfile is](./docs/installation.md#creating-a-new-podfile) | ||
#### Step 0 - Verify Library Linking | ||
## Next Steps | ||
In order to get full branch support you will need to setup your ios and android projects accordingly: | ||
- [iOS](./docs/setup.md#ios) | ||
- [android](./docs/setup.md#android) | ||
*Sometimes rnpm link creates incorrect relative paths, leading to compilation errors* | ||
Please see the branch [SDK Integration Guide](https://dev.branch.io/getting-started/sdk-integration-guide/) for complete setup instructions. | ||
*Ensure that the following files look as described and all linked paths are correct* | ||
## Additional Resources | ||
- [SDK Integration guide](https://dev.branch.io/recipes/add_the_sdk/react/) | ||
- [Testing](https://dev.branch.io/getting-started/integration-testing/guide/react/) | ||
- [Support portal, FAQ](http://support.branch.io/) | ||
```gradle | ||
// file: android/settings.gradle | ||
... | ||
## Usage | ||
```js | ||
import branch from 'react-native-branch' | ||
include ':react-native-branch', ':app' | ||
// Subscribe to incoming links (both branch & non-branch) | ||
branch.subscribe(({params, error, uri}) => { | ||
if (params) { /* handle branch link */ } | ||
else { /* handle uri */ } | ||
}) | ||
// The relative path to the react-native-branch directory tends to often be prefixed with one too many "../"s | ||
project(':react-native-branch').projectDir = new File(rootProject.projectDir, '../node_modules/react-native-branch/android') | ||
``` | ||
let lastParams = await branch.getLatestReferringParams() // params from last open | ||
let installParams = await branch.getFirstReferringParams() // params from original install | ||
branch.setIdentity('theUserId') | ||
branch.userCompletedAction('Purchased Item', {item: 123}) | ||
branch.logout() | ||
```gradle | ||
// file: android/app/build.gradle | ||
... | ||
let branchUniversalObject = branch.createBranchUniversalObject('canonicalIdentifier', {metadata: {prop1: 'test', prop2: 'abc'}, contentTitle: 'Cool Content!', contentDescription: 'Cool Content Description'} | ||
dependencies { | ||
... | ||
compile project(':react-native-branch') | ||
} | ||
``` | ||
let shareOptions = { messageHeader: 'Check this out', messageBody: 'No really, check this out!' } | ||
let linkProperties = { feature: 'share', channel: 'RNApp' } | ||
let controlParams = { $desktop_url: 'http://example.com/home', $ios_url: 'http://example.com/ios' } | ||
let {channel, completed, error} = await branchUniversalObject.showShareSheet(shareOptions, linkProperties, controlParams) | ||
let {url} = await branchUniversalObject.generateShortUrl(linkProperties, controlParams) | ||
let viewResult = await branchUniversalObject.registerView() | ||
let spotlightResult = await branchUniversalObject.listOnSpotlight() | ||
#### Step 1 - Initialize the RNBranchModule | ||
```java | ||
// file: android/app/src/main/java/com/xxx/MainActivity.java | ||
import android.content.Intent; // <-- import | ||
import com.dispatcher.rnbranch.*; // <-- import | ||
public class MainActivity extends ReactActivity { | ||
// ... | ||
@Override | ||
protected List<ReactPackage> getPackages() { | ||
return Arrays.<ReactPackage>asList( | ||
new MainReactPackage(), | ||
new RNBranchPackage() // <-- add this line, if not already there | ||
); | ||
} | ||
// Add onStart | ||
@Override | ||
public void onStart() { | ||
super.onStart(); | ||
RNBranchModule.initSession(this.getIntent().getData(), this); | ||
} | ||
// Add onNewIntent | ||
@Override | ||
public void onNewIntent(Intent intent) { | ||
this.setIntent(intent); | ||
} | ||
// ... | ||
} | ||
let rewards = await branch.loadRewards() | ||
let redeemResult = await branch.redeemRewards(amount, bucket) | ||
let creditHistory = await branch.getCreditHistory() | ||
``` | ||
#### Step 2 - Configure Manifest | ||
## Linking | ||
###### <a id='subscribe'></a>[subscribe(listener)](#subscribe) | ||
**listener** (function) | ||
Adds a change listener. Listener takes 1 argument with the shape `{ params, uri, error}`. The listener will be called for all incoming links. Branch links will have [params](#params), plain deep links will only have a uri. | ||
Please follow [these instructions] (https://dev.branch.io/getting-started/sdk-integration-guide/guide/android/#configure-manifest) | ||
###### <a id='getlatestreferringparams'></a>[getLatestReferringParams(): Promise](#getlatestreferringparams) | ||
Returns a promise that resolves to the most recent referring [params](#params). Because params come in asynchronously, in most cases it is better to use the `subscribe` method to receive the params as soon as they are available. | ||
#### Step 3 - Register for Google Play Install Referrer | ||
###### <a id='getfirstreferringparams'></a>[getFirstReferringParams(): Promise](#getfirstreferringparams) | ||
Returns a promise to resolves with the first install referring [params](#params). | ||
Please follow [these instructions](https://dev.branch.io/getting-started/sdk-integration-guide/guide/android/#register-for-google-play-install-referrer) | ||
###### <a id='params'></a>[params object](#params) | ||
The params object is returned by various linking methods including subscribe, getLatestReferringParams, and getFirstReferringParams. Params will contain any data associated with the Branch link that was clicked before the app session began. | ||
Note: The "receiver" element needs to be added to the "application" node in AndroidManifest.xml | ||
Branch returns explicit parameters every time. Here is a list, and a description of what each represents. | ||
* `~` denotes analytics | ||
* `+` denotes information added by Branch | ||
#### Step 4 - Register a URI scheme | ||
| **Parameter** | **Meaning** | ||
| --- | --- | ||
| ~channel | The channel on which the link was shared, specified at link creation time | ||
| ~feature | The feature, such as `invite` or `share`, specified at link creation time | ||
| ~tags | Any tags, specified at link creation time | ||
| ~campaign | The campaign the link is associated with, specified at link creation time | ||
| ~stage | The stage, specified at link creation time | ||
| ~creation_source | Where the link was created ('API', 'Dashboard', 'SDK', 'iOS SDK', 'Android SDK', or 'Web SDK') | ||
| +match_guaranteed | True or false as to whether the match was made with 100% accuracy | ||
| +referrer | The referrer for the link click, if a link was clicked | ||
| +phone_number | The phone number of the user, if the user texted himself/herself the app | ||
| +is_first_session | Denotes whether this is the first session (install) or any other session (open) | ||
| +clicked_branch_link | Denotes whether or not the user clicked a Branch link that triggered this session | ||
| +click_timestamp | Epoch timestamp of when the click occurred | ||
Please follow [these instructions](https://dev.branch.io/getting-started/sdk-integration-guide/guide/android/#register-a-uri-scheme) | ||
Any additional data attached to the branch link will be available unprefixed. | ||
Notes: | ||
- The "intent-filter" element needs to be added to the activity node, whose android:name is "com.yourAppName.MainActivity". This node is in the "application" node. | ||
- If you already have an intent-filter tag, this has to be added as an additional one. | ||
- Make sure to replace "yourApp" with the scheme you specified in the Branch dashboard. | ||
## User Methods | ||
###### <a id='setidentity'></a>[setIdentity(userId)](#setidentity) | ||
Set an identifier for the current user. | ||
#### Step 5 - Enable Auto Session Management | ||
###### <a id='logout'></a>[logout(userId)](#logout) | ||
Logout the current user. | ||
Please follow [these instructions](https://dev.branch.io/getting-started/sdk-integration-guide/guide/android/#enable-auto-session-management) | ||
###### <a id='usercompletedaction'></a>[userCompletedAction(label, payload)](#usercompletedaction) | ||
Register a user action with branch. | ||
Note: Just add the "android:name" attribute to your "application" node in your AndroidManifest.xml | ||
## Branch Universal Object | ||
###### <a id='createbranchuniversalobject'></a>[createBranchUniversalObject(canonicalIdentifier, universalObjectOptions): object](#createbranchuniversalobject) | ||
Create a branch universal object. | ||
**canonicalIdentifier** the unique identifier for the content. | ||
**universalObjectOptions** options for universal object as defined [below][#universalobjectoptions]. | ||
Returns an object with methods `generateShortUrl`, `registerView`, `listOnSpotlight`, and `showShareSheet`. | ||
#### Step 6 - Enable App Links for Android M and above (Optional but Recommended) | ||
##### The following methods are available on the resulting branchUniversalObject: | ||
###### <a id='showsharesheet'></a>[- showsharesheet(shareOptions, linkProperties, controlParams): object](#showsharesheet) | ||
**shareOptions** as defined [below](#shareoptions) | ||
**linkProperties** as defined [below](#linkproperties) | ||
**controlParams** as defined [below](#controlparams) | ||
Returns an object with `{ channel, completed, error }` | ||
Please follow [these instructions](https://dev.branch.io/getting-started/universal-app-links/guide/android/) | ||
###### <a id='generateshorturl'></a>[- generateShortUrl(linkProperties, controlParams): object](#generateshorturl) | ||
**linkProperties** as defined [below](#linkproperties) | ||
**controlParams** as defined [below](#controlparams) | ||
Returns an object with `{ url }` | ||
### iOS | ||
###### <a id='registerview'></a>[- registerView()](#registerview) | ||
Register a view for this universal object. | ||
#### Step 1 - Modifications to your React Native XCode Project | ||
###### <a id='listonspotlight'></a>[- listOnSpotlight()](#listonspotlight) | ||
List the univeral object in spotlight (ios only). | ||
- Drag and Drop /node_modules/react-native-branch/Pods/Pods.xcodeproj into the Libraries folder of your project in XCode (as described in Step 1 [here](https://facebook.github.io/react-native/docs/linking-libraries-ios.html#content)) | ||
- Drag and Drop the Pods.xcodeproj's Products's libBranch.a into your project's target's "Linked Frameworks and Libraries" section (as described in Step 2 [here](https://facebook.github.io/react-native/docs/linking-libraries-ios.html#content)) | ||
###### <a id='universalobjectoptions'></a>[universalObjectOptions object](#universalobjectoptions) | ||
An object of options for the branchUniversalObject. | ||
| Key | TYPE | DESCRIPTION | | ||
| ------------------- | ------ | ----------------------------------- | | ||
| canonicalIdentifier | String | The object identifier | | ||
| title | String | The object title | | ||
| contentDescription | String | Object Description | | ||
| contentImageUrl | String | The Image URL | | ||
| contentIndexingMode | String | Indexing Mode 'private' or 'public' | | ||
| contentMetadata | Object | Custom key/value | | ||
###### <a id='linkproperties'></a>[linkProperties object](#linkproperties) | ||
An object of link properties. | ||
#### Step 2 - Modifications to AppDelegate.m | ||
| KEY | TYPE | MEANING | ||
| -------- | -------- |------------------------ | ||
| feature | `string` | This is the feature of your app that the link might be associated with. eg: if you had built a referral program, you would label links with the feature `referral` | ||
| alias | `string` | Specify a link alias in place of the standard encoded short URL (e.g., `[branchsubdomain]/youralias or yourdomain.co/youralias)`. Link aliases are unique, immutable objects that cannot be deleted. **Aliases on the legacy `bnc.lt` domain are incompatible with Universal Links and Spotlight** | ||
| channel | `string` | Use channel to tag the route that your link reaches users. For example, tag links with ‘Facebook’ or ‘LinkedIn’ to help track clicks and installs through those paths separately | ||
| stage | `string` | Use this to categorize the progress or category of a user when the link was generated. For example, if you had an invite system accessible on level 1, level 3 and 5, you could differentiate links generated at each level with this parameter | ||
| duration | `int` | duration of the link. | ||
Import RNBranch.h at the top | ||
###### <a id='controlparams'></a>[controlParams object](#controlparams) | ||
Control parameters for the link. | ||
```objective-c | ||
#import "RNBranch.h" | ||
``` | ||
| KEY | TYPE | MEANING | ||
| ------------------ | -------- | -------------------- | ||
| $fallback_url | `string` | Change the redirect endpoint for all platforms - so you don’t have to enable it by platform | ||
| $desktop_url | `string` | Change the redirect endpoint on desktops | ||
| $android_url | `string` | Change the redirect endpoint for Android | ||
| $ios_url | `string` | Change the redirect endpoint for iOS | ||
| $ipad_url | `string` | Change the redirect endpoint for iPads | ||
| $fire_url | `string` | Change the redirect endpoint for Amazon Fire OS | ||
| $blackberry_url | `string` | Change the redirect endpoint for Blackberry OS | ||
| $windows_phone_url | `string` | Change the redirect endpoint for Windows OS | ||
###### <a id='shareoptions'></a>[shareOptions object](#shareoptions) | ||
Initialize the Branch Session in didFinishLaunchingWithOptions | ||
| KEY | TYPE | MEANING | ||
| ------------------ | -------- | -------------------- | ||
| messageHeader | `string` | The header text | ||
| messageBody | `string` | The body text | ||
```objective-c | ||
- (BOOL)application:(UIApplication *)application didFinishLaunchingWithOptions:(NSDictionary *)launchOptions | ||
{ | ||
[RNBranch initSessionWithLaunchOptions:launchOptions isReferrable:YES]; | ||
NSURL *jsCodeLocation; | ||
/// | ||
} | ||
``` | ||
## Referral Methods | ||
###### <a id='loadrewards'></a>[loadRewards()](#loadrewards) | ||
Load rewards. | ||
Add the openURL and continueUserActivity functions | ||
###### <a id='redeemrewards'></a>[redeemRewards(amount, bucket)](#redeemrewards) | ||
Redeem rewards. | ||
**amount** the amount to redeem | ||
**bucket** (optional) the bucket to redeem from. | ||
```objective-c | ||
- (BOOL)application:(UIApplication *)application openURL:(NSURL *)url sourceApplication:(NSString *)sourceApplication annotation:(id)annotation { | ||
if (![RNBranch handleDeepLink:url]) { | ||
// do other deep link routing for the Facebook SDK, Pinterest SDK, etc | ||
} | ||
return YES; | ||
} | ||
- (BOOL)application:(UIApplication *)application continueUserActivity:(NSUserActivity *)userActivity restorationHandler:(void (^)(NSArray *restorableObjects))restorationHandler { | ||
return [RNBranch continueUserActivity:userActivity]; | ||
} | ||
``` | ||
#### Step 3 - Add the branch_key to your plist | ||
Add a String entry branch_key with your branch key to your plist (as described [here](https://dev.branch.io/references/ios_sdk/#add-your-branch-key-to-your-project)) | ||
#### Step 4 - Register a URI Scheme for Direct Deep Linking (Optional but Recommended) | ||
Please follow these instructions [here](https://dev.branch.io/references/ios_sdk/#register-a-uri-scheme-direct-deep-linking-optional-but-recommended) | ||
#### Step 5 - Configure for Universal Linking | ||
Please follow these instructions [here](https://dev.branch.io/references/ios_sdk/#support-universal-linking-ios-9) | ||
###### <a id='getcredithistory'></a>[getCreditHistory(): array](#getcredithistory) | ||
Get the credit history as an array. |
Sorry, the diff of this file is not supported yet
Sorry, the diff of this file is not supported yet
Sorry, the diff of this file is not supported yet
License Policy Violation
LicenseThis package is not allowed per your license policy. Review the package's license to ensure compliance.
Found 1 instance in 1 package
Native code
Supply chain riskContains native code (e.g., compiled binaries or shared libraries). Including native code can obscure malicious behavior.
Found 1 instance in 1 package
New author
Supply chain riskA new npm collaborator published a version of the package for the first time. New collaborators are usually benign additions to a project, but do indicate a change to the security surface area of a package.
Found 1 instance in 1 package
License Policy Violation
LicenseThis package is not allowed per your license policy. Review the package's license to ensure compliance.
Found 1 instance in 1 package
Native code
Supply chain riskContains native code (e.g., compiled binaries or shared libraries). Including native code can obscure malicious behavior.
Found 1 instance in 1 package
No tests
QualityPackage does not have any tests. This is a strong signal of a poorly maintained or low quality package.
Found 1 instance in 1 package
97
1
80536
9
19
2