> ## Documentation Index
> Fetch the complete documentation index at: https://docs.bit2connect.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Link Management

> Understanding dynamic link creation, validation, and best practices

## Link Code Uniqueness

Dynamic links in Bit2Connect use unique codes within each project to ensure reliable routing and prevent conflicts.

### Code Requirements

<Info>
  **Format Rules**:

  * Length: 3-50 characters
  * Allowed: letters (a-z, A-Z), numbers (0-9), hyphens (-), underscores (\_)
  * Case sensitive: `MyCode` and `mycode` are different codes
  * Must be unique within your project
</Info>

### Code Validation Workflow

Before creating a link with a custom code, follow this recommended workflow:

<Steps>
  <Step title="Check Code Availability">
    Use the [Check Code Availability](/api-reference/links/check-code) endpoint to verify if your desired code is available.

    ```bash theme={null}
    GET /1.0/links/check/my-custom-code
    ```
  </Step>

  <Step title="Handle Availability Response">
    * If `available: true` → Proceed with link creation
    * If `available: false` → Choose a different code or let the system generate one
  </Step>

  <Step title="Create Link">
    Use the validated code in your [Create Link](/api-reference/links/create) request.

    ```json theme={null}
    {
      "code": "my-custom-code",
      "payload": { ... }
    }
    ```
  </Step>
</Steps>

### Auto-Generated Codes

If you don't specify a custom code, Bit2Connect automatically generates a unique code:

* **Format**: Random alphanumeric string (8-12 characters)
* **Uniqueness**: Guaranteed unique across the entire platform
* **Examples**: `abc12345`, `xyz789mn`, `def456gh`

## Link Status Management

Dynamic links have different status states that affect their behavior:

### Status Types

<CardGroup cols={2}>
  <Card title="ACTIVE" icon="check-circle" color="#10b981">
    Link is live and routing traffic normally
  </Card>

  <Card title="PAUSED" icon="pause-circle" color="#f59e0b">
    Link is temporarily disabled, returns 404 to users
  </Card>

  <Card title="EXPIRED" icon="clock" color="#ef4444">
    Link has passed its expiration date, automatically paused
  </Card>

  <Card title="DELETED" icon="trash" color="#6b7280">
    Link is soft-deleted, not returned by API calls
  </Card>
</CardGroup>

### Status Transitions

```mermaid theme={null}
graph LR
    A[ACTIVE] --> B[PAUSED]
    B --> A
    A --> C[EXPIRED]
    B --> C
    A --> D[DELETED]
    B --> D
    C --> D
```

<Warning>
  **Expired Links**: You cannot reactivate a link that has passed its `expiresAt` date. The system automatically sets expired links to EXPIRED status.
</Warning>

## Link Payload Structure

The payload defines how your dynamic link behaves across different platforms:

### Required Fields

```json theme={null}
{
  "payload": {
    "link": "https://example.com/destination"  // Required: Primary destination
  }
}
```

### Platform-Specific Routing

<Tabs>
  <Tab title="Android Configuration">
    ```json theme={null}
    "android": {
      "package": "com.example.app",
      "store_fallback": "https://play.google.com/store/apps/details?id=com.example.app",
      "min_version": "1.2.0"
    }
    ```

    * **With App**: Opens directly in your Android app
    * **Without App**: Redirects to Play Store
    * **Version Check**: Ensures minimum app version compatibility
  </Tab>

  <Tab title="iOS Configuration">
    ```json theme={null}
    "ios": {
      "bundleId": "com.example.app",
      "app_store_fallback": "https://apps.apple.com/app/example/id123456789",
      "app_store_id": "123456789",
      "min_version": "1.2.0"
    }
    ```

    * **With App**: Opens directly in your iOS app
    * **Without App**: Redirects to App Store
    * **Universal Links**: Supports iOS Universal Links protocol
  </Tab>

  <Tab title="Social Media">
    ```json theme={null}
    "social": {
      "title": "Check out this amazing product!",
      "description": "Discover the best deals on our mobile app",
      "image": "https://example.com/images/product.jpg"
    }
    ```

    * **Rich Previews**: Enhanced sharing on social platforms
    * **SEO Friendly**: Improves search engine visibility
    * **Brand Consistency**: Maintains visual identity across shares
  </Tab>
</Tabs>

## Analytics & Tracking

### UTM Parameters

Add campaign tracking to measure marketing performance:

```json theme={null}
"campaign": {
  "utm_source": "newsletter",
  "utm_medium": "email",
  "utm_campaign": "summer_sale_2024",
  "utm_term": "mobile_app",
  "utm_content": "cta_button"
}
```

### Click Analytics

Every dynamic link automatically tracks:

* **Click Count**: Total number of clicks
* **Platform Distribution**: iOS vs Android vs Desktop
* **Geographic Data**: Country-level click distribution
* **Referrer Information**: Traffic source analysis

<Tip>
  **Performance Monitoring**: Use the [Get Link](/api-reference/links/get) endpoint to retrieve detailed analytics for any link.
</Tip>

## Best Practices

### Code Naming Conventions

<CardGroup cols={2}>
  <Card title="Campaign Links" icon="megaphone">
    `summer-sale-2024`, `black-friday-email`, `social-promo-q1`
  </Card>

  <Card title="Product Links" icon="shopping-bag">
    `product-123`, `category-electronics`, `featured-item-abc`
  </Card>

  <Card title="Content Links" icon="document-text">
    `blog-post-seo`, `tutorial-video-1`, `whitepaper-download`
  </Card>

  <Card title="Event Links" icon="calendar">
    `webinar-signup`, `conference-2024`, `workshop-registration`
  </Card>
</CardGroup>

### Security Considerations

* **API Key Protection**: Never expose API keys in client-side code
* **Code Predictability**: Avoid sequential or predictable code patterns
* **Expiration Dates**: Set appropriate expiration for time-sensitive campaigns
* **Regular Audits**: Periodically review and clean up unused links

### Performance Optimization

* **Batch Operations**: Use pagination when retrieving large link lists
* **Caching**: Cache link data on your side to reduce API calls
* **Rate Limiting**: Respect the 1000 requests/hour limit
* **Error Handling**: Implement proper retry logic for failed requests

<Warning>
  **Production Deployment**: Always test your dynamic links across different devices and platforms before launching campaigns.
</Warning>