Installation

1. Project Setup

1.1. Prepare Your Project

Make sure your JavaScript-based project is ready to use the Cross SDK.

1.2. Configure npm to use CROSS Nexus Package Registry

Create a .npmrc file in the root of your project and add the following settings:

registry=https://registry.npmjs.org/
@to-nexus:registry=https://package.cross-nexus.com/repository/cross-sdk-js/

1.3. Install the Cross SDK

Install the Cross SDK in your project:

npm install @to-nexus/sdk

yarn add @to-nexus/sdk

pnpm add @to-nexus/sdk

2. Set Environment Variables

Create a .env file and add the required environment variables:

VITE_PROJECT_ID=your_project_id_here
VITE_NODE_ENV=production

PROJECT_ID=your_project_id_here
NODE_ENV=production

projectId is required. You must use a valid project ID.
If you don't have one, please contact the Cross team.
nodeEnv is required and must be set to production:
- production: Production environment for general users
- development: For CROSS chain developers only (developer permission required)

3) SDK Initialization

3.1 Initialize the SDK

Initialize the SDK in the entry point of your application:

// React Example
import {
  initCrossSdk,
} from '@to-nexus/sdk/react'

const projectId = "your_project_id_here"

initCrossSdk(projectId)

// Vanilla JS Example
import { initCrossSdkWithParams } from '@to-nexus/sdk';

const metadata = {
  name: 'Cross SDK',
  description: 'Cross SDK for HTML',
  url: 'https://to.nexus',
  icons: ['https://contents.crosstoken.io/wallet/token/images/CROSSx.svg']
};

// Your unique project id provided by Cross Team. If you don't have one, please contact us.
const projectId = window?.VITE_PROJECT_ID || 'your_project_id_here';
const redirectUrl = window.location.href;

const crossSdk = initCrossSdkWithParams({
  projectId,
  redirectUrl,
  metadata,
  themeMode: 'light'
});

4. Deep Link Configuration

To enable deep linking with the CROSSx app in your JavaScript/React application, you need to configure your app to handle the crossx:// scheme. This allows your app to open the CROSSx wallet when users need to sign transactions or interact with the blockchain.

Web App Configuration

For web applications, you can use the Web App Manifest to handle deep linking. Add the following to your manifest.json:

{
  "name": "Your App Name",
  "short_name": "App",
  "start_url": "/",
  "display": "standalone",
  "background_color": "#ffffff",
  "theme_color": "#000000",
  "protocol_handlers": [
    {
      "protocol": "crossx",
      "url": "/handle-crossx?%s"
    }
  ]
}

React Native Configuration

If you're using React Native, you'll need to configure both iOS and Android:

iOS Configuration

Add the following to your ios/YourApp/Info.plist:

<key>LSApplicationQueriesSchemes</key>
<array>
 <string>crossx</string>
</array>

Android Configuration

Add the following to your android/app/src/main/AndroidManifest.xml:

<queries>
 <intent>
  <action android:name="android.intent.action.VIEW" />
  <data android:scheme="crossx" />
 </intent>
</queries>

Implementation

Here's how to implement deep linking in your JavaScript/React application:

// Check if CROSSx app is installed
const checkCrossxInstalled = async () => {
  try {
    // Try to open CROSSx app
    window.location.href = 'crossx://';
    
    // Set a timeout to detect if the app opened
    setTimeout(() => {
      // If we're still here, the app might not be installed
      console.log('CROSSx app may not be installed');
    }, 1000);
  } catch (error) {
    console.error('Error opening CROSSx app:', error);
  }
};

// Handle deep link return
const handleDeepLinkReturn = () => {
  // Listen for when the app returns from CROSSx
  window.addEventListener('focus', () => {
    // Handle the return from CROSSx app
    console.log('Returned from CROSSx app');
  });
};

// React Hook for deep linking
const useCrossxDeepLink = () => {
  const openCrossxApp = useCallback((action, params) => {
    const url = `crossx://${action}?${new URLSearchParams(params).toString()}`;
    window.location.href = url;
  }, []);

  return { openCrossxApp };
};

import React from 'react';
import { useCrossxDeepLink } from './hooks/useCrossxDeepLink';

const CrossxButton = () => {
  const { openCrossxApp } = useCrossxDeepLink();

  const handleSignTransaction = () => {
    openCrossxApp('sign', {
      transaction: '0x...',
      chainId: '1'
    });
  };

  return (
    <button onClick={handleSignTransaction}>
      Sign with CROSSx
    </button>
  );
};

Additional Considerations

URL Scheme Handling: Your app should also be configured to handle incoming deep links if you want to return to your app after the user completes an action in CROSSx.
Fallback Handling: Consider implementing fallback behavior for cases where the CROSSx app is not installed on the user's device.
Testing: Always test deep linking functionality on both iOS and Android devices to ensure proper integration.
Web App Manifest: For PWA support, ensure your manifest.json includes the protocol handler configuration.
React Native: If using React Native, consider using libraries like react-native-deep-linking for better integration.