앱 설정과 비밀 값
셀러가 채우는 설정(settings), 개발자가 넣는 비밀 값(secrets), 저장·전달·가림 규칙
앱에는 값이 두 종류 있습니다. 설정은 설치한 상점마다 셀러가 채우고, 비밀 값은 개발자가 앱에 한 번 넣습니다. 둘 다 앱 코드가 실행될 때
ctx로 받습니다. 앱 코드에 값을 적어 두지 않습니다.
설정 (settings) | 비밀 값 (secrets) | |
|---|---|---|
| 정하는 곳 | 매니페스트 settings에 필드 선언 | 매니페스트 secrets에 이름 선언 |
| 채우는 사람 | 셀러(상점 플랫폼 앱 › {앱} › 설정) | 개발자(sayren app secret put) |
| 범위 | 설치(상점)마다 | 앱 전체 |
| 읽는 곳 | ctx.settings.{키} | ctx.secrets.{이름} |
| 예 | Slack 웹훅 주소, 알림 최소 금액 | Slack 서명 시크릿, 외부 서비스 API 키 |
설정
설치 직후 상점 플랫폼이 설정 폼을 보여 줍니다. 필수 필드가 비어 있는 동안은 이벤트 함수가 실행되지 않습니다(APP.INSTALLED 제외).
셀러가 저장하면 APP.SETTINGS_UPDATED 이벤트가 옵니다(매니페스트 events에 적었을 때).
secret: true필드는 암호화해 저장합니다. 상점 플랫폼과 관리 API 응답에는 앞 4자와…만 보이고, 저장 폼에서 비워 두면 기존 값을 유지합니다.- 비밀 필드는 AI 에이전트·액세스 토큰으로 읽거나 바꿀 수 없습니다. 상점 플랫폼의 소유자·관리자만 저장합니다.
- 설정값은 앱 코드에만 전달됩니다. 개발자 화면·로그에 보이지 않습니다.
"ORDER.PAID": async (event, ctx) => {
const url = ctx.settings.webhookUrl as string; // secret 필드도 평문으로 읽습니다
const min = Number(ctx.settings.minAmount ?? 0);
}관리 API로도 다룹니다(상점 플랫폼 전용, 소유자·관리자).
| 요청 | 하는 일 |
|---|---|
GET /v1/apps/installations/{installationId} | 설치 상세. settings.fields(폼 정의)·settings.values(비밀은 가린 값)·settings.configured |
PUT /v1/apps/installations/{installationId}/settings | { "values": { … } }. 생략한 비밀 필드는 유지, null은 비움 |
개발자 비밀 값
npx sayren app secret put SLACK_SIGNING_SECRET # 값은 표준 입력으로 받습니다
echo -n "xoxb-…" | npx sayren app secret put SLACK_SIGNING_SECRET
npx sayren app secret list # 이름·마지막 변경 시각만
npx sayren app secret delete SLACK_SIGNING_SECRET- 이름은 매니페스트
secrets에 적어야 합니다. 적지 않은 이름은 거부됩니다. sayren은 올린 버전의 매니페스트로 이름을 확인하므로 첫deploy뒤에 넣습니다(release전이어도 됩니다). 매니페스트에서 이름을 지우면 다음 버전부터 전달되지 않습니다. - 값은 넣는 즉시 모든 설치의 다음 호출부터 전달됩니다. 버전을 다시 올리지 않아도 됩니다.
- 값은 어디에도 다시 보이지 않습니다. 잃어버리면 새 값을 넣습니다.
- 값은 1KB까지입니다.
로컬 실행
npx sayren app dev는 .env의 SAYREN_APP_SETTING_{키}·SAYREN_APP_SECRET_{이름}을 읽어 ctx.settings·ctx.secrets로 넣습니다.
.env는 올라가지 않습니다.
# .env
SAYREN_APP_SETTING_webhookUrl=https://hooks.slack.com/services/…
SAYREN_APP_SETTING_minAmount=10000
SAYREN_APP_SECRET_SLACK_SIGNING_SECRET=…제거 뒤
셀러가 앱을 제거하면 그 설치의 설정은 48시간 뒤 APP.STORE_REDACT와 함께 지워집니다. 비밀 값은 앱 것이라 남습니다.