# Link creation

> Generate smart links programmatically in your web app.

Source: https://docs.grovs.io/docs/sdk/web/link-creation

## Generating a link

```javascript
const url = await Grovs.generateLink({
  title: "Check out this product",
  subtitle: "Limited time offer",
  imageURL: "https://example.com/image.jpg",
  data: { productId: "12345", screen: "product_detail" },
  tags: ["promotion", "share"],
  trackingCampaign: "spring_sale",
  trackingSource: "in_app",
  trackingMedium: "share_button",
});

if (url) {
  await navigator.share({ url });
}
```

`generateLink` resolves the URL string, or `null` on failure. Request failures reach `onError` as `linkGenerationFailed`. The SDK must be configured, authenticated and enabled:

- Before authentication, it resolves `null` and reports once per page load.
- While disabled, it resolves `null` silently.

## Parameters

Every field is optional.

| Parameter                | Type              | Description                                                                                                                                |
| ------------------------ | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| `title`                  | `string`          | Link preview title                                                                                                                         |
| `subtitle`               | `string`          | Link preview subtitle                                                                                                                      |
| `imageURL`               | `string`          | Link preview image URL                                                                                                                     |
| `data`                   | `object`          | Custom payload delivered when the link is opened. Must be JSON-serializable                                                                |
| `tags`                   | `string[]`        | Tags for filtering and analytics                                                                                                           |
| `customRedirects`        | `CustomRedirects` | Override the default redirect per platform. See [Custom redirects](#custom-redirects)                                                      |
| `showPreviewiOS`         | `boolean`         | Show the link preview page on iOS. Omit to use the project default                                                                         |
| `showPreviewAndroid`     | `boolean`         | Show the link preview page on Android. Omit to use the project default                                                                     |
| `copyToClipboardiOS`     | `boolean`         | Copy the link to the clipboard from the iOS preview page, so the native SDK can match a fresh install. Omit to inherit the project setting |
| `copyToClipboardAndroid` | `boolean`         | Same, for Android                                                                                                                          |
| `trackingCampaign`       | `string`          | Campaign name, for example `"BlackFriday2025"`                                                                                             |
| `trackingSource`         | `string`          | Traffic source, for example `"instagram"`, `"newsletter"`                                                                                  |
| `trackingMedium`         | `string`          | Medium, for example `"cpc"`, `"email"`, `"social"`                                                                                         |

`copyToClipboardiOS` and `copyToClipboardAndroid` apply only when that platform shows the preview page. Passing `false` is an explicit override, unlike omitting the field. The web SDK never reads the clipboard: the preview page copies, and the [iOS](https://docs.grovs.io/docs/sdk/ios/deep-linking#clipboard-assisted-deferred-deep-linking) and [Android](https://docs.grovs.io/docs/sdk/android/deep-linking#clipboard-assisted-deferred-deep-linking) SDKs read it back after install. Full flow: [Copy to Clipboard](https://docs.grovs.io/docs/links/copy-to-clipboard).

## Custom redirects

Override where a link sends users per platform:

```javascript
const url = await Grovs.generateLink({
  title: "Special offer",
  data: { promoId: "summer25" },
  customRedirects: {
    ios: { link: "https://example.com/ios-promo" },
    android: { link: "https://example.com/android-promo" },
    desktop: { link: "https://example.com/desktop-promo" },
  },
});
```

For `ios` and `android`, an omitted `openAppIfInstalled` is sent as `false`, so the redirect URL is always used. Set `true` to open the app if installed, otherwise use the redirect URL. `desktop` has no such flag.

## Getting link details

```javascript
const details = await Grovs.linkDetails("abc123");
```

Resolves the record for a link the SDK generated in the current environment, by path, or `null` when the path is unknown.

## Next steps

- [Receive deep link payloads →](https://docs.grovs.io/docs/sdk/web/deep-linking)
- [Full API reference →](https://docs.grovs.io/docs/sdk/web/api-reference)