# Link creation

> Generate smart links from your Unity game with the Grovs SDK.

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

Create smart links from the game with `GenerateLinkAsync`, then share them.

## Generating a link

```csharp
using System.Collections.Generic;
using GrovsSDK;
using UnityEngine;

async void ShareInvite()
{
    try
    {
        string link = await Grovs.GenerateLinkAsync(new GenerateLinkOptions
        {
            Title = "Join my team",
            Subtitle = "Level 3 is waiting",
            ImageUrl = "https://example.com/share.png",
            Data = new Dictionary<string, object> { { "level", 3 }, { "inviter", "player-42" } },
            Tags = new List<string> { "invite" },
            TrackingCampaign = "spring",
            TrackingSource = "in_game",
            TrackingMedium = "share_button"
        });
        GUIUtility.systemCopyBuffer = link;
    }
    catch (GrovsException e)
    {
        Debug.LogWarning("Link failed: " + e.Error);
    }
}
```

The callback version passes the error instead of throwing:

```csharp
Grovs.GenerateLink(options, (link, error) =>
{
    if (error != null) Debug.LogWarning(error);
    else Debug.Log(link);
});
```

Both complete on the Unity main thread. A `null` options object creates a link with no metadata.

## Options

Every field of `GenerateLinkOptions` is optional. A `null` field is left out of the request.

| Field                    | Type                          | Description                                                                                                                                                                                                                                    |
| ------------------------ | ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Title`                  | `string`                      | Link preview title                                                                                                                                                                                                                             |
| `Subtitle`               | `string`                      | Link preview subtitle                                                                                                                                                                                                                          |
| `ImageUrl`               | `string`                      | Link preview image URL                                                                                                                                                                                                                         |
| `Data`                   | `IDictionary<string, object>` | Custom payload delivered in [`DeeplinkReceived`](https://docs.grovs.io/docs/sdk/unity/deep-linking)                                                                                                                                            |
| `Tags`                   | `IList<string>`               | Tags for filtering and analytics                                                                                                                                                                                                               |
| `IosRedirect`            | `GrovsRedirect`               | Where the link sends iOS visitors                                                                                                                                                                                                              |
| `AndroidRedirect`        | `GrovsRedirect`               | Where the link sends Android visitors                                                                                                                                                                                                          |
| `DesktopRedirect`        | `GrovsRedirect`               | Where the link sends desktop visitors                                                                                                                                                                                                          |
| `ShowPreviewIos`         | `bool?`                       | Show the link preview on iOS. `null` uses the dashboard default.                                                                                                                                                                               |
| `ShowPreviewAndroid`     | `bool?`                       | Show the link preview on Android. `null` uses the dashboard default.                                                                                                                                                                           |
| `CopyToClipboardIos`     | `bool?`                       | Copy the link to the visitor's clipboard on the iOS preview page, for [clipboard-assisted deferred deep linking](https://docs.grovs.io/docs/sdk/unity/deep-linking#clipboard-assisted-deferred-deep-linking). `null` uses the project setting. |
| `CopyToClipboardAndroid` | `bool?`                       | Same, for the Android preview page.                                                                                                                                                                                                            |
| `TrackingCampaign`       | `string`                      | UTM campaign                                                                                                                                                                                                                                   |
| `TrackingSource`         | `string`                      | UTM source                                                                                                                                                                                                                                     |
| `TrackingMedium`         | `string`                      | UTM medium                                                                                                                                                                                                                                     |

`Data` values must be JSON-serializable: strings, numbers, booleans, `null`, lists and string-keyed dictionaries of these. Anything else throws `ArgumentException` before the request is sent.

## Custom redirects

`GrovsRedirect` overrides where a link sends visitors on one platform:

```csharp
var options = new GenerateLinkOptions
{
    Title = "Spring event",
    AndroidRedirect = new GrovsRedirect { Url = "https://example.com/android", OpenAppIfInstalled = true },
    DesktopRedirect = new GrovsRedirect { Url = "https://example.com/event", OpenAppIfInstalled = false }
};
```

| Field                | Type     | Default | Description                                            |
| -------------------- | -------- | ------- | ------------------------------------------------------ |
| `Url`                | `string` | none    | The redirect URL. A redirect without a URL is ignored. |
| `OpenAppIfInstalled` | `bool`   | `true`  | Open the game instead when it's installed.             |

## Errors

The task fails with a [`GrovsException`](https://docs.grovs.io/docs/sdk/unity/api-reference#grovsexception) whose `Error.Code` is:

| Code                   | When                                                                                      |
| ---------------------- | ----------------------------------------------------------------------------------------- |
| `LinkGenerationFailed` | The backend didn't return a link.                                                         |
| `SdkDisabled`          | Grovs is disabled. See [Privacy & Consent](https://docs.grovs.io/docs/sdk/unity/privacy). |
| `SdkNotInitialized`    | The native SDK didn't start, for example because the API key is empty.                    |
| `UnsupportedPlatform`  | Running in the Editor or on a platform other than iOS and Android.                        |
| `Unknown`              | Android: another native failure. `Error.Message` has the details.                         |

While authentication is still retrying, iOS waits until it succeeds and then generates the link. Android fails right away.

## See also

- [Deep linking](https://docs.grovs.io/docs/sdk/unity/deep-linking): receive the payload when the link opens
- [Create a link](https://docs.grovs.io/docs/links/create-link): links from the dashboard