Introduction

1. Prerequisites

To follow this guide, you will need to:

2. Install and initialize the CodeQR TypeScript SDK

Install

Install the CodeQR TypeScript SDK using your preferred package manager:

npm
yarn
pnpm

npm install @codeqr/ts

yarn add @codeqr/ts zod # zod is a peer dependency

pnpm add @codeqr/ts

Initialize

Then, initialize the CodeQR TypeScript SDK with your API key.

lib/codeqr.ts

import CodeQR from "@codeqr/ts";

export const codeqr = new CodeQR({
  apiKey: process.env.CODEQR_API_KEY, // optional, defaults to CODEQR_API_KEY env variable
});

You can now use the codeqr object to interact with the CodeQR API.

import { codeqr } from "./lib/codeqr";

3. Create link

Let’s create a short link using the CodeQR TypeScript SDK.

create-link.ts

const { shortLink } = await codeqr.links.create({
  url: "https://google.com",
});

console.log(shortLink); // e.g. https://codeqr.link/abc123

Full list of available attributes for the Link model

string

required

The destination URL of the short link.

string

The domain of the short link. If not provided, the primary domain for the project will be used (or codeqr.link if the project has no domains).

string

The short link slug. If not provided, a random 7-character slug will be generated.

string | null

This is the ID of the link in your database. If set, it can be used to identify the link in the future.

string | null

The ID of the tenant that created the link inside your system. If set, it can be used to fetch all links for a tenant.

string

The prefix of the short link slug for randomly-generated keys (e.g. if prefix is /c/, generated keys will be in the /c/:key format). Will be ignored if key is provided.

boolean

default:false

Whether to track conversions for the short link.

string | null

The identifier of the short link that is unique across your project. If set, it can be used to identify your short link for client-side click tracking.

boolean

default:false

Whether the short link is archived.

boolean

default:false

Whether the short link’s stats are publicly accessible.

string

The unique IDs of the tags assigned to the short link.

string | string[]

The unique name of the tags assigned to the short link (case insensitive).

string | null

The comments for the short link.

string | null

The date and time when the short link will expire at.

string | null

The URL to redirect to when the short link has expired.

string | null

The password required to access the destination URL of the short link.

boolean

default:false

Whether the short link uses Custom Social Media Cards feature.

string | null

The title of the short link generated via api.codeqr.io/metatags. Will be used for Custom Social Media Cards if proxy is true.

string | null

The description of the short link generated via api.codeqr.io/metatags. Will be used for Custom Social Media Cards if proxy is true.

string | null

The image of the short link generated via api.codeqr.io/metatags. Will be used for Custom Social Media Cards if proxy is true.

string | null

The custom link preview video (og:video). Will be used for Custom Social Media Cards if proxy is true. Learn more: https://d.to/og

boolean

default:false

Whether the short link uses link cloaking.

string | null

The iOS destination URL for the short link for iOS device targeting.

string | null

The Android destination URL for the short link for Android device targeting.

boolean

default:false

Allow search engines to index your short link. Defaults to false if not provided. Learn more: https://d.to/noindex

string | null

The UTM source of the short link. If set, this will populate or override the UTM source in the destination URL.

string | null

The UTM medium of the short link. If set, this will populate or override the UTM medium in the destination URL.

string | null

The UTM campaign of the short link. If set, this will populate or override the UTM campaign in the destination URL.

string | null

The UTM term of the short link. If set, this will populate or override the UTM term in the destination URL.

string | null

The UTM content of the short link. If set, this will populate or override the UTM content in the destination URL.

string | null

The referral tag of the short link. If set, this will populate or override the ref query parameter in the destination URL.

string | null

The ID of the program the short link is associated with.

string[] | null

An array of webhook IDs to trigger when the link is clicked. These webhooks will receive click event data.

Optionally, you can also pass an externalId field which is a unique identifier for the link in your own database to associate it with the link in CodeQR’s system.

create-link-external-id.ts

await codeqr.links.create({
  url: "https://google.com",
  externalId: "12345",
});

This will let you easily update the link or retrieve analytics for it later on using the externalId instead of the CodeQR linkId.

4. Upsert link

CodeQR TypeScript SDK provides a method to upsert a link – where an existing link is updated if it exists, or a new link is created if it doesn’t. so you don’t have to worry about checking if the link already exists.

upsert-link.ts

const { shortLink } = await codeqr.links.upsert({
  url: "https://www.google.com",
});

console.log(shortLink); // will always be the same short link

This way, you won’t have to worry about checking if the link already exists when you’re creating it.

5. Update link

Let’s update an existing link using the CodeQR TypeScript SDK. You can do that in two ways:

Using the link’s linkId in CodeQR’s system.
Using the link’s externalId in your own database (prefixed with ext_).

update-link.ts

// Update a link by its linkId
await codeqr.links.update("link_rWOKByP0bRMrstK8e4HPjprJ", {
  url: "https://www.google.uk", // new URL
});

// Update a link by its externalId
await codeqr.links.update("ext_12345", {
  url: "https://www.google.uk", // new URL
});

6. Retrieve analytics for link

CodeQR allows you to retrieve analytics for a link using the CodeQR TypeScript SDK.

get-analytics.ts

import { ClicksTimeseries } from "codeqr/models/components";

// Retrieve the timeseries analytics for the last 7 days for a link
const response = await codeqr.analytics.retrieve({
  linkId: "clv3o9p9q000au1h0mc7r6l63",
  interval: "7d",
  groupBy: "timeseries",
});

const timeseries = response as ClicksTimeseries[];

Similarly, you can retrieve analytics for a link using the externalId field.

get-analytics-external-id.ts

import { ClicksTimeseries } from "codeqr/models/components";

// Retrieve the timeseries analytics for the last 7 days for a link
const response = await codeqr.analytics.retrieve({
  externalId: "ext_12345",
  interval: "7d",
  groupBy: "timeseries",
});

const timeseries = response as ClicksTimeseries[];

7. Examples

TypeScript Example

See the full example on GitHub.

Overview

SDKs

APIs

1. Prerequisites

2. Install and initialize the CodeQR TypeScript SDK

Install

Initialize

3. Create link

4. Upsert link

5. Update link

6. Retrieve analytics for link

7. Examples

TypeScript Example

​1. Prerequisites

​2. Install and initialize the CodeQR TypeScript SDK

Install

Initialize

​3. Create link

​4. Upsert link

​5. Update link

​6. Retrieve analytics for link

​7. Examples

TypeScript Example

1. Prerequisites

2. Install and initialize the CodeQR TypeScript SDK

3. Create link

4. Upsert link

5. Update link

6. Retrieve analytics for link

7. Examples