이 문서는 그룹 앱 기능의 사용 방법을 안내합니다.

그룹 앱은 2개 이상의 앱을 하나의 그룹으로 묶는 기능입니다. 그룹은 하나의 대표 앱과 멤버 앱들로 구성됩니다. 여러 서비스에서 하나의 통합 멤버십 서비스를 제공하는 경우 등, 사용자 가입 및 정보를 연관 서비스끼리 공유해야 할 때 사용합니다. 이 기능을 사용하려면 카카오싱크 운영 담당자에게 그룹으로 묶을 앱들의 ID 목록을 전달하여 그룹 앱 설정을 요청해야 합니다.

여러 개의 앱이 하나의 그룹으로 묶이기 위해서는 아래 조건을 만족해야 합니다.

• 대표 앱을 기준으로 한 통합 회원 시스템이 있어야 합니다.
• 모든 소속 앱들이 비즈니스 채널과 연결되어 있어야 하고, 비즈니스 인증 심사를 완료한 상태여야 합니다. 멤버 앱의 서비스 약관은 대표 앱의 서비스 약관들을 반드시 포함해야 합니다.
• 통합 회원 시스템에서 멤버 앱(제휴 서비스)로 개인정보를 제공하거나, 사업자 혹은 서비스 회원가입 시 모든 서비스에서 추가 가입 없이 기존에 가입한 계정을 사용할 수 있어야 합니다.
• 위 사항이 통합 회원 시스템의 개인정보 처리방침에 기록되어 있고, 카카오와 사용자가 확인할 수 있어야 합니다.
• (통합 회원 시스템으로 운영될 경우) 제휴 서비스 회원 가입 화면에서 통합 회원 시스템으로 가입해야 합니다.
• 대표 앱의 소유자(Owner)가 멤버 앱들의 에디터(Editor) 이상 권한을 가지고 있어야 합니다.

• 대표 앱 아이콘은 통합 회원 시스템을 대표해야 합니다.
• 각 앱 이름은 제휴 서비스 이름과 통합 회원 시스템 이름을 결합한 형태로 등록해야 합니다.

그룹마다 대표 앱은 하나 뿐이고, 대표 앱이 바뀌면 그룹 구성 정보가 완전히 바뀌어 새로 만든 것과 다름 없어집니다. 즉, 대표 앱을 변경해서는 안 됩니다. 대표 앱을 바꾸는 일 없도록 미리 검토하고 준비해야 합니다.

또한 멤버 앱은 사용자와 카카오 로그인으로 각각 연결되어야 합니다. 사용자가 그룹 대표 앱이나 멤버 앱 중 하나에 연결되었을 때, 그룹 안의 다른 멤버 앱들과 자동으로 연결되지 않습니다.

테스트 앱도 그룹의 대표 앱 또는 멤버 앱이 될 수 있으며, 테스트 앱만으로 그룹을 구성할 수도 있습니다.

그룹에 속한 앱들은 사용자 정보에 그룹 사용자 토큰(group_user_token) 정보를 추가로 받습니다. 그룹 사용자 토큰은 한 그룹 안에서 사용자가 이미 가입한 서비스의 회원 정보대로 다른 서비스의 회원 정보를 연동(맵핑, Mapping)하기 위한 참고 정보로 사용합니다.

주의해야 할 점으로, group_user_token은 ID 용도로는 사용할 수 없습니다. 그룹 대표 앱이 바뀌는 등 그룹 구성 정보가 변경되면 값이 바뀌기 때문입니다. 이 값은 그룹 내에서 같은 사용자인지 확인하기 위한 부수적인 참고 정보일 뿐이므로 사용자 구분을 위해서는 별도 ID를 저장해 사용해야 합니다.

그룹 사용자 토큰은 사용자가 그룹에 속한 앱과 연결될 때 발급됩니다. 회원번호(user_id)는 동일 사용자라도 앱마다 다른 값으로 발급되지만, 그룹 사용자 토큰은 동일 사용자의 경우 같은 그룹 내 모든 앱에서 동일한 값으로 발급되기 때문에, 그룹 내에서 동일 사용자 여부를 확인할 수 있습니다.

그룹 앱에 소속된 앱은 사용자 정보 요청 API의 응답에 그룹 사용자 토큰인 group_user_token 값을 추가로 받습니다. 이 값은 그룹 안에서 유일한 값이고, 그룹에 속한 앱끼리 같은 사용자인지 확인하는 연동(맵핑, Mapping) 정보로 참고할 수 있습니다.

사용자 정보 요청 API는 회원번호(user id)나 액세스 토큰(Access Token)으로만 조회할 수 있고, group_user_token으로는 요청할 수 없습니다.

플랫폼별 사용자 정보 요청 API 개발 문서는 아래 바로가기를 참고합니다.

• Android SDK
• iOS SDK
• JavaScript
• REST API

curl -v -G GET "https://kapi.kakao.com/v2/user/me" \
-H "Authorization: Bearer ${ACCESS_TOKEN}"

// HTTP/1.1 200 OK
{
  "id": 123456789,
  "group_user_token": "${GROUP_TOKEN}",
  "properties": {
    "${CUSTOM_PROPERTY_KEY}": "${CUSTOM_PROPERTY_VALUE}"
    // ...
  },
  "kakao_account": {
    "email_needs_agreement": false,
    "is_email_valid": true,
    "is_email_verified": true,
    "email": "xxxxxxx@xxxxx.com",
    "age_range_needs_agreement": false,
    "age_range": "20~29",
    "birthday_needs_agreement": false,
    "birthday": "1130",
    "gender_needs_agreement": false,
    "gender": "female"
  }
}

// /v2/user/me API 호출
UserManagement.getInstance().me(new MeV2ResponseCallback() {
    @Override
    public void onFailure(ErrorResult errorResult) {
        // API 에러.
    }
    @Override
    public void onSessionClosed(ErrorResult errorResult) {
        // 토큰이 만료되고 갱신 불가능한 상태.
    }
    @Override
    public void onSuccess(MeV2Response result) {
        Log.d("group_token", result.getGroupUserToken());
    }
});

// 사용자 정보 조회
KOSessionTask.userMeTask(completion: { (error, me) in
    if let me = me {
        guard let groupUserToken = me.groupToken else { return }
        // 조회한 그룹 토큰 사용
        <#code#>
    }
})

사용자가 그룹에 속한 앱 중 어떤 앱에 연결돼 있는지 확인합니다.

사용자가 카카오 로그인한 뒤 발급되는 액세스 토큰 값을 헤더에 담아 요청하며, 응답은 대상 사용자의 그룹 사용자 토큰(group_user_token)과 연결되어 있는 앱별 회원번호(user id) 목록을 반환합니다.

응답의 회원번호 목록인 group_info에는 해당 사용자가 연결되어 있는 앱의 정보만 포함되므로, 이 목록에 특정 앱들이 포함되어 있지 않다면 사용자가 이용하지 않는 앱이라는 의미입니다.

// HTTP/1.1 200 OK
{
  "group_info": [
    {
      "app": {
        "company": "회사명",
        "id": 12345,
        "name": "앱이름1"
      },
      "user_id": 123456789
    },
    {
      "app": {
        "company": "회사명2",
        "id": 67890,
        "name": "앱이름2"
      },
      "user_id": 987654321
    }
  ],
  "group_user_token": "${GROUP_TOKEN}"
}