Skip to content

Commit

Permalink
docs: manifest updates [LIVE-12009] (#359)
Browse files Browse the repository at this point in the history
  • Loading branch information
@Justkant
Justkant authored May 23, 2024
1 parent e92bbfc commit d15c65d
Show file tree
Hide file tree
Showing 4 changed files with 115 additions and 156 deletions.
205 changes: 88 additions & 117 deletions apps/docs/pages/APIs/wallet-api/appendix/manifest.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -14,66 +14,38 @@ To test and integrate your application, you first need to write your application

You don't have to fill in all the fields; we'll fill them in once your integration has been confirmed.

However, here are a few elements you'll need to fill in yourself and their descriptions :
However, here are a few elements you'll need to fill in yourself and their descriptions :

_To be filled in by you_

| Properties | Descripton | Type | Requirements |
|------------------|-----------------|------------------|-----------------------------|
| id | uniq id of your app | string | a-z | 0-9 | |
| _author_ | Name of your organisation | string | optional | * |
| _name_ | Name of your live app (will be displayed and used to search your app inside the Discover section) | string | * |
| _url_ | Url of the live app homepage (users will be redirected to this link once they open your app) | string (URL) | * |
| _homepageUrl_ | Url of your organisation | string (URL) | optional | * |
| _supportUrl_ | Your support url | string (URL) | optional | * |
| _icon_ | Icon URL (will be displayed inside the Discover section) | string (URL) | optional | * |
| platforms | Platform compatibility | Array(enum) | "ios", "android", "desktop" |
| apiVersion | Specific manifest schema version (leave it as [default](#default-values)) | string | * |
| manifestVersion | Version supported by the app that the wallet needs to implement in order to support (leave it as [default](#default-values)) | enum | 2 |
| categories | List of category related to your Live App ([example](#default-values)) | Array(string) | items: min 1 → * |
| currencies | currencies supported by your Live App | Array(string) | items: min 1 → * |
| _content_ | Descripton of your Live App (will be displayed inside the Discover section) | Object | \{shortDescription: string, description: string, subtitle: string (optional)\} | |
| [permissions](#permissions) | List of permissions you will need in order to interact with wallet-api | enum | |
| _domains_ | ___ | Array(string) | optional | * |
| [type](#params) | Type of you Live app | enum | "dapp", "walletApp", "webBrowser" |
| [params](#params) | ___| Object | depend on the type |
| visibility | Visibility of your live app inside Ledger Live. (Leave it as [default](#default-values)) | string | "complete", "searchable", "deep" |

### Params

#### params when `type = "dapp"`

_Your app uses the [ETH DApp Browser](https://github.com/LedgerHQ/eth-dapp-browser)_

| Params | Type | Requirements |
|-----------|-----------------|-------------------------------------------|
| dappUrl | string (URL) | * |
| nanoApp | string | * |
| dappName | string | * |
| networks | Array (unique Object) | (chainID: number, nodeURL: string, currency: enum) |


#### params when `type = "walletApp"`

_Your app uses the [Wallet API](https://github.com/LedgerHQ/wallet-api)_

| Params | Type | Requirements |
|-----------|-----------|--------------------|
| any param | any | optional | * |



#### params when `type = "webBrowser"`

_Your app uses the [Platform App Web Browser](https://github.com/LedgerHQ/platform-app-web-browser)_


| Params | Type | Requirements |
|-------------|-----------------|-----------------|
| webUrl | string (URL) | * |
| webAppName | string | * |
| currencies | Array (enum) | "ethereum", "bitcoin", ... |

| Properties | Descripton | Type | Requirements |
| --------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | ------------- | ------------------------------------------------------------------------------ |
| id | uniq id of your app | string | a-z \| 0-9 \| |
| _author_ | Name of your organisation | string | optional \| \* |
| _name_ | Name of your live app (will be displayed and used to search your app inside the Discover section) | string | \* |
| _url_ | Url of the live app homepage (users will be redirected to this link once they open your app) | string (URL) | \* |
| _homepageUrl_ | Url of your organisation | string (URL) | optional \| \* |
| _supportUrl_ | Your support url | string (URL) | optional \| \* |
| _icon_ | Icon URL (will be displayed inside the Discover section) | string (URL) | optional \| \* |
| platforms | Platform compatibility | Array(enum) | "ios", "android", "desktop" |
| apiVersion | Specific manifest schema version (leave it as [default](#default-values)) | string | \* |
| manifestVersion | Version supported by the app that the wallet needs to implement in order to support (leave it as [default](#default-values)) | enum | 2 |
| categories | List of category related to your Live App ([example](#default-values)) | Array(string) | items: min 1 → \* |
| currencies | currencies supported by your Live App | Array(string) | items: min 1 → \* |
| _content_ | Descripton of your Live App (will be displayed inside the Discover section) | Object | \{shortDescription: string, description: string, subtitle: string (optional)\} |
| [permissions](#permissions) | List of permissions you will need in order to interact with wallet-api | enum | |
| _domains_ | \_\_\_ | Array(string) | optional \| \* |
| [dapp](#dapp) | \_\_\_ | Object | (nanoApp: string, networks: Array (unique Object)) |
| visibility | Visibility of your live app inside Ledger Live. (Leave it as [default](#default-values)) | string | "complete", "searchable", "deep" |

### Dapp

_Your app uses the [DApp Browser](../../../docs/discover/dapp-browser)_

| Params | Type | Requirements |
| -------- | --------------------- | -------------------------------------------------- |
| nanoApp | string | \* |
| networks | Array (unique Object) | (chainID: number, nodeURL: string, currency: enum) |

#### Permissions

Expand All @@ -83,8 +55,8 @@ Permissions that allow your app to interact with methods :
"permissions": [

// Account and currencies
"account.list",
"account.receive",
"account.list",
"account.receive",
"account.request",
"currency.list",

Expand All @@ -105,8 +77,7 @@ Permissions that allow your app to interact with methods :

],

```

```

#### Default values

Expand All @@ -121,7 +92,7 @@ _Complete manifest.json file with default or examples values :_
"exampleParam": "value"
},
"homepageUrl": "http://localhost:3000/",
"platform": ["ios","android","desktop"],
"platform": ["ios", "android", "desktop"],
"apiVersion": "^2.0.0",
"manifestVersion": "2",
"branch": "stable",
Expand All @@ -136,7 +107,7 @@ _Complete manifest.json file with default or examples values :_
}
},
"permissions": [],
"domains": ["http://*"],
"domains": ["http://", "https://"],
"visibility": "complete"
}
```
Expand All @@ -145,7 +116,7 @@ _Complete manifest.json file with default or examples values :_

### Introduction to Overrides

In the context of app manifests, the **overrides** feature offers a powerful mechanism to create conditional modifications to your manifest. With this feature, you can specify different values for specific conditions, such as Ledger Live versions (`llVersion`) and device (`platform`). This ensures a tailored experience across multiple versions and platforms without the need for separate manifest files.
In the context of app manifests, the **overrides** feature offers a powerful mechanism to create conditional modifications to your manifest. With this feature, you can specify different values for specific conditions, such as Ledger Live versions (`llVersion`) and device (`platform`). This ensures a tailored experience across multiple versions and platforms without the need for separate manifest files.

### Structure of Overrides

Expand All @@ -155,63 +126,66 @@ Inside your manifest, you can include an `overrides` section to define condition

`Request: /api/v1/apps?llVersion=1.0.0`

``` Example:
"overrides": [
{
"version": "1.0.0",
"changes": {
"name": "overridden manifest"
}
}
]
```
In this example, users with Ledger Live version `1.0.0` will see the app name as "overridden manifest".
```Example:
"overrides": [
{
"version": "1.0.0",
"changes": {
"name": "overridden manifest"
}
}
]
```

In this example, users with Ledger Live version `1.0.0` will see the app name as "overridden manifest".

2. **Platform Overrides**: Enables you to tailor the manifest for specific platforms like iOS, Android, etc.

Request param:
Request param:

- `/api/v1/apps?platform=ios`
- `/api/v1/apps?platform=android`

```Example:
"overrides": [
{
"platform": "ios",
"changes": {
"name": "overridden for iOS"
}
},
{
"platform": "android",
"changes": {
"name": "overridden for Android"
}
}
]
```


``` Example:
"overrides": [
{
"platform": "ios",
"changes": {
"name": "overridden for iOS"
}
},
{
"platform": "android",
"changes": {
"name": "overridden for Android"
}
}
]
```
Depending on the user's device platform, they will see a different app name – "overridden for iOS" on Apple devices and "overridden for Android" on Android devices.
Depending on the user's device platform, they will see a different app name – "overridden for iOS" on Apple devices and "overridden for Android" on Android devices.

## Depth Limitation in Overrides

Only the first depth of fields can be overridden, meaning granular changes to nested properties are not supported directly. To override a field with nested properties, the entire field, including all nested properties, must be redefined.

For example, you cannot override just a nested `url`:
```
For example, you cannot override just a nested `url`:

```
"overrides": [
{
"platform": "ios",
"changes": {
"params": {
"url": "new-url"
}
}
}
{
"platform": "ios",
"changes": {
"params": {
"url": "new-url"
}
}
}
]
```

Instead, you need to redefine the entire `params` field:

```
"overrides": [
{
Expand All @@ -233,22 +207,19 @@ Overrides are activated when the manifest is requested with specific parameters.

1. **ledgerLiveVersion**: Activated by calling with the `llVersion` parameter.

Will return all defaults manifests with the 1.0.0 overr if it exist:
Will return all defaults manifests with the 1.0.0 overr if it exist:

`http://localhost:3000/api/v1/apps?llVersion=1.0.0`
`http://localhost:3000/api/v1/apps?llVersion=1.0.0`

2. **Platform**: Activated by calling with the `platform` parameter. The `platforms` field inside the manifest will be replaced accordingly.

Will return all defaults manifests and override for iOS and replace the `platforms` field in the manifest with `["ios"]` if it exist inside the manifest :

`http://localhost:3000/api/v1/apps?platform=ios`

Will return all defaults manifests and override for iOS and replace the `platforms` field in the manifest with `["ios"]` if it exist inside the manifest :

`http://localhost:3000/api/v1/apps?platform=ios`

3. **Combining Parameters**: You can combine multiple parameters to activate multiple overrides.

Apply overrides for both Ledger Live version `1.0.0` and the `iOS` platform :

`http://localhost:3000/api/v1/apps?llVersion=1.0.0&platform=ios`
Apply overrides for both Ledger Live version `1.0.0` and the `iOS` platform :
`http://localhost:3000/api/v1/apps?llVersion=1.0.0&platform=ios`

## Priority in Overrides

Expand All @@ -258,10 +229,9 @@ In cases where both `ledgerLiveVersion` and `platform` might have overriding val

When a request specifies a platform, such as 'ios' (?platform=ios), the system performs an override process as follows:


`Request: ?platform=ios`

```
```
Manifest before override:
{
"platforms": ["desktop", "android"],
Expand All @@ -279,7 +249,8 @@ Manifest before override:
It begins with the main manifest as the default.
Searches for any overrides within the manifest relevant to the requested platform (here "platform": "ios"), and applies them to the default fields.
Returns a manifest specific for the requested platform, in this case 'ios'.
``` Resulting manifest.json:

```Resulting manifest.json:
{
"platforms": ["ios"],
"visibility": "searchable"
Expand Down
38 changes: 20 additions & 18 deletions apps/docs/pages/APIs/wallet-api/examples/live-app-creation/manifest.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,23 +6,12 @@ A manifest file is necessary to test your Live App inside Ledger Live. Create a

```json
{
"$schema": "https://live-app-catalog.ledger.com/schema.json",
"id": "SampleLiveApp",
"name": "SampleLiveApp",
"url": "http://localhost:3000/",
"params": {
"dappUrl": "http://localhost:3000/",
"nanoApp": "SampleLiveApp",
"dappName": "SampleLiveApp",
"networks": [
{
"currency": "ethereum",
"chainID": 1,
"nodeURL": "..."
}
]
},
"homepageUrl": "http://localhost:3000/",
"platform": ["ios","android","desktop"],
"platform": ["ios", "android", "desktop"],
"apiVersion": "^2.0.0",
"manifestVersion": "2",
"branch": "stable",
Expand All @@ -36,13 +25,26 @@ A manifest file is necessary to test your Live App inside Ledger Live. Create a
"en": "Desc"
}
},
"permissions": [],
"domains": ["http://*"],
"permissions": [
"account.list",
"account.receive",
"account.request",
"currency.list",
"message.sign",
"transaction.sign",
"transaction.signAndBroadcast",
"wallet.capabilities",
"wallet.info",
"wallet.userId"
],
"domains": ["http://", "https://"],
"visibility": "complete"
}
```

<Callout emoji="💡">
For more informations regarding the setting up of a manifest, please refer to [the manifest page](../../appendix/manifest)
For more informations regarding the setting up of a manifest, please refer to
[the manifest page](../../appendix/manifest)
</Callout>

### 10. **Importing Manifest in Ledger Live**
Expand All @@ -56,6 +58,6 @@ Now you'll see a new row in the menu with the name of your Live App. You can now

---

This concludes the step-by-step guide to developing a Live App for Ledger Live from scratch.
This concludes the step-by-step guide to developing a Live App for Ledger Live from scratch.

Have any questions or suggestions for improvement? Leave an issue in our repo or reach out to us through our Discord.
Have any questions or suggestions for improvement? Leave an issue in our repo or reach out to us through our Discord.
Loading

0 comments on commit d15c65d

Please sign in to comment.