> For the complete documentation index, see [llms.txt](https://developer.usemultiplier.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://developer.usemultiplier.com/multiplier-embed-sdks/installation-and-configuration.md).
# Installation & Configuration
If you are integrating the SDK into an existing application, follow these detailed steps to ensure proper authentication and configuration.
### 1. Registry Authentication
The SDK is hosted on the GitHub Package Registry. You must configure your package manager to look at `npm.pkg.github.com` for the `@Multiplier-Core` scope.
> **Important:** You need a GitHub Personal Access Token (PAT) with `read:packages` permissions.
#### Option A: Project-level Configuration (Recommended)
**For NPM or Yarn 1 (Classic)** Create an `.npmrc` file in your project root:
```
@Multiplier-Core:registry=https://npm.pkg.github.com
//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}
```
**For Yarn 2+ (Berry)**
Create a .yarnrc.yml file in your project root:
```
npmScopes:
Multiplier-Core:
npmAlwaysAuth: true
npmAuthToken: "${GITHUB_TOKEN}"
npmPublishRegistry: "https://npm.pkg.github.com"
npmRegistryServer: "https://npm.pkg.github.com"
```
#### Option B: Global Configuration
You can also set this globally on your machine if you work across multiple projects:
```
npm config set @Multiplier-Core:registry https://npm.pkg.github.com
npm config set //npm.pkg.github.com/:_authToken YOUR_GITHUB_TOKEN
```
### 2. Install Package
Once the registry is configured and your `GITHUB_TOKEN` is exported in your environment, install the package:
```
# Using Yarn
yarn add @Multiplier-Core/partner-sdk-react
# Using NPM
npm install @Multiplier-Core/partner-sdk-react
```
### 3. Global Config Provider
The `MultiplierGlobalConfigProvider` is the root component that must wrap any part of your app using Multiplier features. It handles the authentication state and global settings.
#### The Builder Pattern
We use a fluent builder pattern (`createGlobalConfig`) to construct the configuration object safely.
#### Implementation Example
Wrap your application (or the specific route where Multiplier features live) with the provider:
```tsx
import {
createGlobalConfig,
MultiplierGlobalConfigProvider
} from '@Multiplier-Core/partner-sdk-react';
import '@Multiplier-Core/partner-sdk-react/dist/index.css'; // Don't forget CSS!
function App({ children }) {
// 1. Create the configuration
const config = createGlobalConfig()
.setAccessToken('your-jwt-access-token')
.setRefreshToken('your-jwt-refresh-token')
.setRemoteOrigin('http://localhost:5173') // Your app's URL
.setEnvironment('production') // 'stg', 'release', or 'production'
.setOnTokenRefreshed((newToken) => {
// Callback to save the new token to your local storage/state
console.log('Token refreshed:', newToken);
})
.setOnError((error) => {
// Handle global errors (e.g. log to Sentry)
console.error('SDK Error:', error);
})
.setTheme({
colors: {
"background-brand": "#0055FF"
}
})
.setI18n({
// Optional i18n configuration
cimode: false,
resources: {
'translation': {
'custom.key': 'Custom translation'
}
}
})
.build();
// 2. Wrap your app
return (
{children}
);
}
```
### 4. Configuration Reference
The `createGlobalConfig()` builder supports the following methods:
| Method | Parameters | Description |
| --------------------- | ----------------------------------------- | ---------------------------------------------------------------------- |
| `setAccessToken` | `token: string` | Required. Sets the initial JWT access token. |
| `setRefreshToken` | `token: string` | Required. Sets the refresh token for auto-renewal. |
| `setEnvironment` | `env: 'stg' \| 'release' \| 'production'` | Sets the environment. Defaults to 'production'. |
| `setRemoteOrigin` | `origin: string` | The origin URL (e.g., `http://localhost:5173`) used for proxy headers. |
| `setHeaders` | `headers: Record` | Custom headers to inject into every API request. |
| `setTheme` | `theme: Partial` | Object to override default colors, spacing, and fonts. |
| `setOnTokenRefreshed` | `(token: string) => void` | Callback triggered when the SDK successfully refreshes a token. |
| `setOnError` | `(err: OnErrorPayload) => void` | Global error handler for network or GraphQL errors. |
| `setI18n` | `i18n: I18nConfig` | Configuration for internationalization. |
#### Props Definition
**MultiplierGlobalConfigProvider Props**
| Prop | Type | Required | Description |
| ---------- | ------------------------ | -------- | --------------------------- |
| `children` | `React.ReactNode` | Yes | Your application components |
| `config` | `MultiplierGlobalConfig` | No | Global configuration object |
**MultiplierGlobalConfig Properties**
| Property | Type | Required | Description |
| ------------------ | --------------------------------- | -------- | --------------------------------------------------------------------- |
| `theme` | `Theme` | Yes | Theme customization object |
| `accessToken` | `string` | Yes | JWT access token for authentication |
| `refreshToken` | `string` | Yes | JWT refresh token for automatic token refresh |
| `remoteOrigin` | `string` | No | Remote origin for proxy configuration (e.g., `http://localhost:5173`) |
| `headers` | `Record` | No | Custom headers for API requests |
| `onError` | `(error: OnErrorPayload) => void` | No | Error handler callback |
| `onTokenRefreshed` | `(accessToken: string) => void` | No | Token refresh callback |
| `i18n` | `I18nConfig` | No | Internationalization configuration |
**OnErrorPayload Properties**
| Property | Type | Description |
| --------------- | --------------- | ----------------------------------------------------- |
| `graphQLErrors` | `GraphQLErrors` | GraphQL errors from the API |
| `networkError` | `NetworkError` | Network errors (connection issues, HTTP errors, etc.) |
**I18nConfig Properties**
| Property | Type | Description |
| ----------- | ---------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `cimode` | `boolean` | When set to `true`, enables Content Interface Mode, which displays translation keys instead of translated text. Useful for identifying keys to override. |
| `resources` | `Record>` | Custom translation resources to override default translations. Structure is `namespace: { key: "value" }`. |
#### Theme Properties
Check **CSS & Customization** for more information.
#### I18n Properties
Check **Label Customization** for more information.
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:
```
GET https://developer.usemultiplier.com/multiplier-embed-sdks/installation-and-configuration.md?ask=&goal=
```
`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.