LLM 으로 구축하기
아래 프롬프트를 Claude Code, Codex, Cursor에 붙여 넣으면 프로젝트에 Human Plugin 셀피 Journey(humantoken 및 humantoken+revalidation 플로우)를 연동할 수 있습니다. 에이전트는 백엔드 스택과 프론트엔드 플랫폼을 감지하고, 백엔드 클라이언트를 만든 다음, 해당 플랫폼의 캡처 단계만 연결합니다. 실제 기기에서의 라이브 셀피 캡처, Unico 지원팀을 통한 도메인 등록, 실제 자격 증명은 사용자의 몫이므로 에이전트는 거기서 멈추고 넘겨줍니다.
# Integrate the Human Plugin selfie journey
## Role and objective
You are a senior engineer integrating the Human Plugin selfie journey into the project in the current working directory. Human Plugin is a service the customer runs. Your back-end creates a process; the person takes a selfie in a hosted page or in the Journeys SDK; your back-end then reads the outcome.
Deliver, in the existing codebase and following its conventions:
1. A back-end client that creates a journey process, persists what it must, reads the outcome and handles failures.
2. The capture step for the ONE front-end platform you detect: Web, Android, iOS, Ionic, React Native, or Flutter.
3. Tests, and a final report.
Use only the facts below. Do not invent endpoints, headers, fields, states or SDK options. If something you need is not in this prompt, ask the developer.
## Facts you can rely on
Back-end contract:
- Only your back-end calls Human Plugin. It has NO caller authentication, NO TLS and NO webhook. Send no access-key header on any call. Never call it from a browser or a mobile app.
- Endpoints: `POST /v1/processes` (create), `GET /v1/processes/{id}` (read). `GET /v1/processes/{id}/selfie` returns the selfie of a finished process for a limited time; call it only if the product must keep the selfie, and never store it in logs or in the repository.
- Journey flows: `humantoken` and `humantoken+revalidation`. The person takes the selfie in a hosted page or in the Journeys SDK.
- Create body, common fields: `flow`, `clientId`, `correlationId`, `credential`.
- The `credential` key is always required. Send `{ "type": "<type>", "value": "<value>" }` when the project has a document, and `null` or `{}` when it has none. Omitting the key, or sending empty strings, returns `400 MISSING_CREDENTIAL_TYPE`. `credential.type` must be an exact, case-sensitive attribute catalog code, or the create returns `422 ATTRIBUTE_TYPE_NOT_SUPPORTED`.
- Limits: `flow` 64 bytes, `clientId` and `correlationId` 128 bytes, `credential.value` 64 bytes. The body can be up to 2 MiB, or the create returns `400 REQUEST_TOO_LARGE`.
- Create body, Journey fields: `callbackUri` and `companyBranchId`. `companyBranchId` is the id of the branch registered at dashboard.unico.app.
- Create body, revalidation only: `references`, as `[{ "referenceType": "REFERENCE_TYPE_HUMAN_TOKEN", "referenceContent": "<humanToken.value>" }]`.
- A successful create answers `201` with `state` `PROCESS_STATE_CREATED`, `id`, `token` and `link`. `token` and `link` come back ONLY on this create answer. Human Plugin never stores them, and a later `GET` does not return them.
- `correlationId` must be unique for every attempt. Reuse it only when retrying after a `503` on create. If that retry answers `409` `CORRELATION_ID_ALREADY_USED`, start a new attempt with a new `correlationId`.
- Set the HTTP client timeout to at least 60 seconds.
- When the person returns to `callbackUri` (or the Journeys SDK `onFinish` fires with `FINISH`), the capture ended, not how it ended. The outcome comes ONLY from `GET /v1/processes/{id}`.
- Only a read advances a pending process. The return to `callbackUri` does not update Human Plugin. If the person never returns, the process stays `PROCESS_STATE_CREATED`.
- Human Plugin does not scope reads by caller: anyone who can reach it can read any process by `id`.
- States: `PROCESS_STATE_CREATED`, `PROCESS_STATE_FINISHED`, `PROCESS_STATE_FAILED`. `FINISHED` is not "approved". Read `data.liveness.value` (`live` or `not_live`) first, and treat `not_live` as failed and ask the person to retry. Then read `data.humanToken` (`value`, with `status` `validated`). In revalidation read `data.humanTokenMatch` instead: only the string `"true"` confirms the same person, and anything else means not confirmed and carries no `ndocs`. `data.ndocs` may be absent.
- Error body: `{ "message": "MISSING_CLIENT_ID", "details": [] }`.
Retries:
- Create `400`, `409`, `422` from Human Plugin itself (request validation, `CORRELATION_ID_ALREADY_USED`, `ATTRIBUTE_TYPE_NOT_SUPPORTED`): nothing was stored. Fix the request. After `409` use a new `correlationId`.
- Create refused by the flow (`400`, `403` or `409` with a flow message, such as `PERMISSION_DENIED`, `DUPLICATE_IMAGE` or the monthly process limit): the process was stored as failed. Use a new `correlationId`.
- Create `401` with an empty `message`: the Unico access key configured on the container (`HUMAN_API_ACCESS_KEY`, server-side, never sent by your back-end) was refused. The process was stored as failed. Do not retry.
- Create `503`: retry with the SAME `correlationId`. Human Plugin answers `503` both when the process was not stored and when it was stored but Unico was never called. In the second case the retry answers `409` `CORRELATION_ID_ALREADY_USED`: this is expected, so start a new attempt with a new `correlationId`.
- Create `502` or `500`: do NOT retry automatically. The result is not confirmed. A new create needs a new `correlationId`.
- `GET` `502`, `503` or a network error: retry with backoff. `GET` `404` `PROCESS_NOT_FOUND`: stop.
- Record each attempt, keyed by `correlationId`, BEFORE calling create.
Capture surfaces:
- Web, hosted link: redirect to `link`, or `window.open` it in a new tab and watch for the return to `callbackUri`.
- Web, Journeys SDK: `npm install unico-journey-sdk`. Call `ByUnicoSDK.init({ token })`, then `ByUnicoSDK.open({ transactionId: id, token, onFinish, onWidgetVisibilityChange })`. `ByUnicoSDK.close()` closes it. `onFinish` receives `type` `FINISH` (the capture ended) or `CLOSE` (the person closed it before the end), and `transaction.redirectUrl` only on `FINISH`. The page must use HTTPS and its domains must be registered by Unico support. If the page already sends `Content-Security-Policy` or `Permissions-Policy` headers, they must allow the Unico origins listed on the Web integration page. Never edit the SDK files. The SDK does not work inside a mobile WebView, or inside your own `<iframe>`; open the `link` instead.
- Android: Custom Tabs, API 26 or later, `androidx.browser:browser:1.5.0`. The activity needs `launchMode="singleTop"`, `exported="true"`, and an intent filter (`VIEW`, `DEFAULT`, `BROWSABLE`) on your scheme and host, plus the `CAMERA` permission. A WebView is a fallback only, and never with the Journeys SDK inside it.
- iOS: `ASWebAuthenticationSession`, iOS 13 or later, Xcode 14 or later. `callbackURLScheme` is the scheme without `://`.
- Ionic: Capacitor 4 or later. A Capacitor plugin wraps the iOS and Android mechanisms above and exposes `openSession({ url })`.
- React Native: 0.71 or later. A native module wraps them and exposes `openSession(url)`.
- Flutter: 3 or later. A `MethodChannel` wraps them and calls `openSession` with `url`.
- For the native and hybrid platforms the back-end sends `callbackUri` as `myapp://callback` (your own unique scheme) and returns `id` and `link` to the app. The app opens the `link`, and the scheme brings the person back.
## Phase 1: read-only discovery
Inspect the repository before writing code. Do not modify anything in this phase.
1. Back-end: language, framework, HTTP client, config and secrets handling, test runner, logging, and any existing Human Plugin client.
2. Front-end: detect the platform. Look for `package.json` (Web, Ionic, React Native), `AndroidManifest.xml` or `build.gradle` (Android), `*.xcodeproj` or `Info.plist` (iOS), `capacitor.config.*` (Ionic), `react-native` in dependencies (React Native), `pubspec.yaml` (Flutter).
3. If more than one platform is present, ask the developer which one to wire. Wire only that one.
4. For Web, ask whether to use the hosted `link` or the Journeys SDK, unless the code already shows the choice.
Ask the developer, in one message, only what you cannot infer:
- The non-production Human Plugin base URL.
- The `clientId` and the `companyBranchId` values. Never invent them.
- The flow: `humantoken` or `humantoken+revalidation`. If `humantoken+revalidation`, where the earlier `humanToken.value` is stored.
- Whether the project has a document to send as `credential`, and its attribute type.
- For native and hybrid platforms: the app's unique URL scheme and host for `callbackUri`.
- For Web: the full page URL the person returns to, used as `callbackUri` (for example `https://app.example.com/capture/done`).
What you automate: code, configuration, tests and documentation in the repository.
What you hand off: the live capture on a real device, the domain registration with Unico support, the URL scheme registration and store review, and every real credential.
## Phase 2: guardrails
Do:
- Call Human Plugin only from the back-end, through one small client module.
- Read the base URL, `clientId` and `companyBranchId` from configuration.
- Persist `id`, `token`, `link` and `correlationId` for each attempt, and record the attempt before calling create. Once the process is final, persist its outcome too and do not read it again: every read of a finished process adds a row to Human Plugin's audit table, which is never pruned. One exception: a `FINISHED` answer with `live` but without `data.ndocs` may be read again with bounded backoff, because a later read computes `ndocs` again. A missing `ndocs` never means the person was not seen before.
- Read the outcome only from `GET /v1/processes/{id}`.
- Check `data.liveness.value` before trusting any other field.
- In the back-end endpoint that reads an outcome by `id`, check that the `id` belongs to the signed-in user.
- Follow the project's existing code style, error handling and test setup.
Do not:
- Send any access-key header, or call Human Plugin from a browser or a mobile app.
- Treat the return to `callbackUri`, `onFinish`, or `FINISHED` as approval.
- Reuse a `correlationId`, except after a `503` on create. If that retry answers `409` `CORRELATION_ID_ALREADY_USED`, use a new one.
- Retry `500` or `502` on create automatically.
- Log or print documents, selfies, tokens, links or `humanToken` values.
- Embed the Journeys SDK in a mobile WebView or in your own `<iframe>`.
- Run a real create against production, or with real personal data.
- Invent endpoints, headers, fields, states, SDK options or environment variables.
- Send fields that Human Plugin refuses: `clientReference`, `client_id`, `correlation_id`, or any other spelling of its own fields. They answer `400 INVALID_REQUEST`. A misspelled optional field is passed to Unico and may be silently ignored, so check every field name against the facts above.
## Phase 3: prerequisites
Confirm with the developer before you rely on them:
- A Human Plugin container is running and reachable from the back-end at a non-production URL.
- The `clientId` and the `companyBranchId` are valid for that installation.
- For Web with the Journeys SDK: Unico support registered the page's domains, and the page uses HTTPS.
- For native and hybrid platforms: the URL scheme is unique to the app.
Add `HUMAN_PLUGIN_URL` to the project's configuration and to `.env.example` (or the project's equivalent) with a placeholder value. Do not name it `HUMAN_API_URL`: that name belongs to the container, where it points to the Unico API. Add the `clientId` and the `companyBranchId` the same way. Do not write real values into the repository.
If the URL is not reachable, say so in the final report. Do not claim the integration works.
## Phase 4: implementation
### Step 1: back-end client
Create one client module with two operations.
Create a journey process:
```bash
curl -sS -X POST "$HUMAN_PLUGIN_URL/v1/processes" \
-H "Content-Type: application/json" \
-d '{
"flow": "humantoken",
"clientId": "<clientId>",
"correlationId": "<unique per attempt>",
"credential": { "type": "<type>", "value": "<value>" },
"callbackUri": "<callbackUri>",
"companyBranchId": "<companyBranchId>"
}'
```
Create a revalidation process, without a document:
```bash
curl -sS -X POST "$HUMAN_PLUGIN_URL/v1/processes" \
-H "Content-Type: application/json" \
-d '{
"flow": "humantoken+revalidation",
"clientId": "<clientId>",
"correlationId": "<unique per attempt>",
"credential": null,
"callbackUri": "<callbackUri>",
"companyBranchId": "<companyBranchId>",
"references": [
{ "referenceType": "REFERENCE_TYPE_HUMAN_TOKEN", "referenceContent": "<humanToken.value>" }
]
}'
```
Read a process:
```bash
curl -sS "$HUMAN_PLUGIN_URL/v1/processes/<id>"
```
Requirements:
- Timeout of at least 60 seconds.
- Generate a new `correlationId` for every attempt, and record the attempt before calling create.
- On `201`, persist `id`, `token`, `link` and `correlationId`. `token` and `link` are not returned again. Once the process is final, persist its outcome and stop reading it, except for a `FINISHED` `live` answer without `data.ndocs`, which may be read again with bounded backoff.
- Always send the `credential` key: the object when the project has a document, `null` when it has none. Send `references` only for `humantoken+revalidation`.
- Map the error body `{ "message": "...", "details": [] }` to typed errors. Do not parse the message beyond matching known codes.
### Step 2: error handling
| Call | Response | Cause | Action |
|---|---|---|---|
| Create | `400`, `422` from Human Plugin (`INVALID_REQUEST`, `REQUEST_TOO_LARGE`, `MISSING_<FIELD>`, `INVALID_<FIELD>`, `ATTRIBUTE_TYPE_NOT_SUPPORTED`) | Invalid request. Nothing stored. | Fix the request before trying again. |
| Create | `409` `CORRELATION_ID_ALREADY_USED` | The `correlationId` was used. | Retry with a new `correlationId`. |
| Create | `400`, `403` or `409` with a flow message (`PERMISSION_DENIED`, `DUPLICATE_IMAGE`, the monthly process limit, and others) | The flow refused it. Stored as failed. | Do not retry the same request. A new attempt needs a new `correlationId`. `PERMISSION_DENIED` means the access key is not enabled for the flow; tell the developer. |
| Create | `401` with an empty `message` | The container's access key was refused. Stored as failed. | Do not retry. Tell the developer to check `HUMAN_API_ACCESS_KEY` on the container. |
| Create | `503` | Database unavailable. The process may already be stored, without Unico being called. | Retry with the SAME `correlationId`, with backoff. If the retry answers `409` `CORRELATION_ID_ALREADY_USED`, start a new attempt with a new `correlationId`. Alert on repeated `503`. |
| Create | `502`, `500` | Not confirmed. | No automatic retry. A new create needs a new `correlationId`. |
| Read | `502`, `503`, network error | Temporary. | Retry with backoff. |
| Read | `404` `PROCESS_NOT_FOUND` | Unknown or deleted `id`. | Stop. |
### Step 3: reading the outcome
After the person returns, call `GET /v1/processes/{id}`:
| State | Final? | What to do |
|---|---|---|
| `PROCESS_STATE_CREATED` | No | Not finished yet. Only a read advances it; the return to `callbackUri` does not. Read again with backoff. |
| `PROCESS_STATE_FINISHED` | Yes | Read `data.liveness.value`. If `not_live`, treat as failed and ask the person to retry. If `live`, read `data.humanToken` and `data.ndocs`. If `data.ndocs` is absent, read again with bounded backoff; a missing `ndocs` never means the person was not seen before. In revalidation, only `data.humanTokenMatch` equal to the string `"true"` confirms the same person. This is not approval. |
| `PROCESS_STATE_FAILED` | Yes | The process ended without a result. Offer a new attempt with a new `correlationId`. |
Expose the result to the rest of the project as a typed value. Do not log its content.
### Step 4: hand the journey to the front-end
Return `id` and `link` to the front-end. Return `token` only for the Web Journeys SDK, never for the hosted link or for native and hybrid platforms. Do not return anything else from the create answer. Add a back-end endpoint the front-end calls to start an attempt, and one it calls after the return to read the outcome. The read endpoint checks that the `id` belongs to the signed-in user.
### Step 5: capture step, for the detected platform only
Implement ONLY the branch that matches the platform from Phase 1.
- Web, hosted link: redirect to `link`, or `window.open` it and watch for the return to `callbackUri`. After the return, call your back-end to read the outcome.
- Web, Journeys SDK: install `unico-journey-sdk`. Call `ByUnicoSDK.init({ token })`, then `ByUnicoSDK.open({ transactionId: id, token, onFinish })`. In `onFinish`, on `FINISH` call your back-end to read the outcome. On `CLOSE` the person closed it before the end: do not assume a result, and let them open it again. Do not touch the SDK iframe or its files. Do not use it in a WebView or your own `<iframe>`.
- Android: open `link` in Custom Tabs (`androidx.browser:browser:1.5.0`, API 26 or later). Register the activity with `launchMode="singleTop"`, `exported="true"`, the intent filter on your scheme and host, and the `CAMERA` permission. In `onNewIntent`, check the scheme and call your back-end to read the outcome.
- iOS: open `link` with `ASWebAuthenticationSession`, with `callbackURLScheme` set to the scheme without `://`. When the callback arrives, call your back-end to read the outcome.
- Ionic: add a Capacitor plugin that exposes `openSession({ url })` and resolves with the callback URL, backed by `ASWebAuthenticationSession` on iOS and Custom Tabs on Android. Register the scheme on both. Then call your back-end to read the outcome.
- React Native: add a native module that exposes `openSession(url)`, backed by the same two mechanisms. Register the module, the scheme and the Android intent filter. Then call your back-end to read the outcome.
- Flutter: add a `MethodChannel` that calls `openSession` with `url`, backed by the same two mechanisms. Register the plugin on both platforms and the scheme. Then call your back-end to read the outcome.
For the native and hybrid platforms set `callbackUri` to your own unique scheme, for example `myapp://callback`.
## Phase 5: verification
Run what you can run, and report each result as it happened.
1. Run the project's linter, type check and tests. Add tests for the client: create success, `409` with a new `correlationId`, `503` retried with the same `correlationId`, `503` whose retry answers `409` `CORRELATION_ID_ALREADY_USED` and starts a new attempt with a new `correlationId`, `500` and `502` not retried, `FINISHED` with `not_live`, `FINISHED` with `live`, `FINISHED` with `live` but without `data.ndocs` read again with bounded backoff, and `FAILED`.
2. Confirm that no access-key header is sent, and that no document, selfie, token, link or `humanToken` is logged.
3. If the developer gave a non-production URL and it is reachable, run one create with synthetic data and one read. Otherwise mark them "not run".
4. Do not run the capture. It needs a real person on a real device.
## Phase 6: definition of done
- The client creates a journey process, persists `id`, `token`, `link` and `correlationId`, reads the outcome, and persists the final outcome instead of reading it again, except to recover a missing `ndocs` with bounded backoff.
- Retries follow the table, with a new `correlationId` where required.
- The capture step exists for the detected platform only.
- The return to `callbackUri`, or `onFinish` with `FINISH`, triggers a read, and is never treated as approval.
- The `credential` key is always sent, and the read endpoint checks that the `id` belongs to the signed-in user.
- `liveness.value` is checked before any other field.
- Configuration has placeholders only, and the repository has no real values.
- Tests pass, or the failures are reported.
## Phase 7: final report
Report, in this order:
1. The platform and model you detected, and the files you added or changed.
2. The commands you ran and their real results. Mark every command you did not run as "not run".
3. The assumptions you made, and anything you could not confirm.
4. What remains for the developer: start the container and confirm the `clientId` and `companyBranchId`; ask Unico support to register the web domains; register the URL scheme and pass store review; test the capture with a real person on a real device.
프로세스 생성 및 오류 및 재시도 페이지에서 각 호출의 요청과 응답을 확인하세요. 연동 후 발생할 수 있는 문제는 문제 해결을 참고하세요.