Mocco

서버나 앱에서 링크 만들기

콘솔 외에 Mocco API로도 링크를 만들 수 있습니다. 서버는 시크릿 키로 링크를 관리하고, 앱은 퍼블리셔블 키로 공유 링크("이 항목 공유" 버튼)를 만듭니다.

먼저 콘솔에서와 같은 준비가 필요합니다. 딥링크를 켜고, 링크 호스트를 정하고, iOS나 Android 앱을 등록하세요(딥링크 개요 참고).

1. 키 만들기

키는 프로젝트의 API 키에서 소유자와 관리자가 만듭니다.

  • 서버용으로는 시크릿 키를 만듭니다. 링크를 만들고 바꾸려면 links:write, 링크와 클릭 수를 읽으려면 links:read를 고릅니다. 이 키는 서버에만 두세요. Mocco는 브라우저에서 보낸 시크릿 키를 거부합니다.

  • 앱용으로는 links:app이 있는 퍼블리셔블 키를 만듭니다. 공유 링크만 만들 수 있으므로 앱에 넣어 배포해도 안전합니다.

2. 서버에서 링크 만들기

Node에서는 @mocco/node를 씁니다.

import { createMoccoServer } from '@mocco/node';

const mocco = createMoccoServer({ secretKey: process.env.MOCCO_SECRET_KEY! });

const link = await mocco.links.create({
  slug: 'spring',
  deepLinkPath: '/sale/spring',
  campaign: 'spring-2026',
  fallbacks: { web: 'https://shop.example.com/spring' },
  og: { title: '봄 세일', description: '최대 50% 할인' },
});
console.log(link.url); // https://acme.<링크 도메인>/spring

시크릿 키로는 콘솔에서 할 수 있는 모든 것을 정할 수 있습니다. 슬러그, 이름, 경로, 파라미터, 캠페인, 웹 대체 주소, 공유 미리보기, 만료일입니다. 콘솔에서처럼 웹 대체 주소는 소유를 확인한 웹 목적지에 있어야 합니다. 같은 클라이언트로 링크 목록을 보고(list), 하나를 읽고(get), 바꾸고(update, 슬러그는 바뀌지 않습니다), 끄고 켜고, 날짜별 클릭 수를 읽습니다(stats(id, { from, to })).

다른 언어에서는 Authorization: Bearer <시크릿 키>로 API를 직접 부르세요. API 설명은 /v1/links/openapi.json에 있습니다.

시크릿 키로 바꾼 내용은 감사 로그에 키를 만든 사람이 한 일로 남고, 어떤 키였는지도 기록됩니다.

3. 앱에서 공유 링크 만들기

퍼블리셔블 키로 앱은 다음 항목만으로 공유 링크를 만듭니다.

  • deepLinkPath: 링크가 앱에서 열 위치. 예: /items/42

  • params (선택): 앱이 링크와 함께 받는 값

  • campaign (선택)

  • og.title, og.description (선택): 공유 미리보기 문구

const response = await fetch('https://<Mocco API 주소>/v1/links', {
  method: 'POST',
  headers: { authorization: `Bearer ${publishableKey}`, 'content-type': 'application/json' },
  body: JSON.stringify({ deepLinkPath: '/items/42', og: { title: '42번 상품' } }),
});
const { url } = await response.json();

슬러그는 Mocco가 만들고, 앱이 없는 사람은 앱의 스토어 페이지로 갑니다. 공유 링크는 슬러그, 이름, 웹 대체 주소, 이미지, 만료일을 정할 수 없습니다. 정하려고 하면 Mocco가 field_not_allowed로 답하며 그 항목을 알려 줍니다. 그래서 누군가 앱에서 키를 빼내도 내 앱 안으로 가는 링크밖에 만들 수 없습니다.

같은 내용이면 같은 링크입니다. 앱이 같은 경로, 파라미터, 캠페인, 문구로 다시 요청하면 Mocco는 새 링크 대신 전에 만든 링크를 돌려줍니다. 그래서 공유 버튼을 누를 때마다 링크가 생기지 않습니다.

한도. 키 하나는 1분에 공유 링크를 60개까지 만들 수 있고, 프로젝트의 앱들은 하루에 새 공유 링크를 5,000개까지 만들 수 있습니다. 한도를 넘으면 Mocco가 429와 Retry-After로 답합니다. 이미 있는 링크를 다시 요청하는 것은 그래도 됩니다.

공유 링크도 콘솔의 링크 목록에 다른 링크처럼 나옵니다. 악용되는 링크가 있으면 거기서 끄세요. 그러면 앱이 그 링크를 다시 만들 수 없습니다.