친구

친구 API는 앱에 가입한 사용자의 카카오톡 친구 중 정보를 제공해주는 API 입니다. 카카오계정 로그인을 사용하는 앱에서 사용할 수 있습니다.

  • 앱에 가입된 친구만 대상이 됩니다.
  • '서비스 내 친구목록' 정보 제공에 동의한 친구만 목록에 포함되고, 친구 리스트 중 친구 정보 제공에 동의하지 않은 경우 목록에서 제외됩니다.

API 활용 범위

  • 카카오톡 친구 정보를 활용하여 애플리케이션의 소셜 서비스를 구축 할 수 있습니다.
  • 해당 애플리케이션에 카카오톡 로그인을 통해서 서비스를 이용하는 친구들 중 카카오 '서비스 내 친구목록' 개인 정보 제공에 동의한 친구만 대상이 됩니다.
  • 사용자들의 친구 관계를 다른 사용자에게 제공해줄 수 없습니다.
  • 친구 정보를 따로 저장할 수 없습니다.
  • 친구들의 관계 정보를 분석/조합해서 제공해줄 수 없습니다.

시작하기 전에

  1. 앱 생성 가이드를 참고하여 빠진 부분이 없는지 확인합니다.
  2. 앱 사인(sign)과정에 사용한 키를 설정 > 일반 > 플랫폼 > Android > 키 해시 에 등록한 상태인지 확인합니다.

    키 해시를 생성하는 방법은 앱 생성의 키해시 등록 과정을 참고 합니다.

Gradle 설정

그래들의 repositories와 dependencies를 아래와 같이 설정해 주셔야 합니다.


// Root project의 build.gradle
subprojects {
    repositories {
        mavenCentral()
        maven { url 'http://devrepo.kakao.com:8088/nexus/content/groups/public/' }
    }
}

// Module의 build.gradle
dependencies {
    implementation 'com.kakao.sdk:friends:1.11.1'
    or
    implementation 'com.kakao.sdk:kakaotalk:1.11.1'
}

친구목록 조희

친구 정보가 많을 수 있기 때문에 사용하는 클라이언트에서는 paging 기반으로 요청해야 합니다. 이를 위해 요청 파라미터로 offset, limit 이 제공되고 전달한 offset 인덱스부터 limit 개만큼의 결과를 가져옵니다.

해당 paging 기반 요청을 기준으로 더 불러올 친구 목록이 있는 경우, 응답 JSON 프로퍼티로 after_url이 주어지고 해당 url을 통해 다음 친구 paging을 요청하면 됩니다. 안드로이드 SDK에서는 위와 같은 기능을 AppFriendContext를 통하여 제공합니다.

AppFriendContext

Name Type Description
secureResource Boolean 이미지 url을 secure url(http/https)로 받을 것인지 여부.
offset int 가져올 친구 리스트의 시작 offset.
limit int 한 페이지에 가져올 친구 최대 수. (최대 100개)
order String 친구 리스트 정렬 순서. (“asc” or “desc”)
beforeUrl String 이전 페이지 url. SDK에서 자동으로 채워줌.
afterUrl String 다음 페이지 url. SDK에서 자동으로 채워줌.

요청이 성공하면 아래와 같은 응답을 콜백으로 전달받습니다.

AppFriendsResponse

Name Type Description
friends List\ 패이징 된 AppFriendInfo 리스트
totalCount Integer 정보를 얻을 수 있는 전체 친구 수
beforeUrl String 이전 페이지 url
afterUrl String 다음 페이지 url

AppFriendInfo

Name Type Description
userId Long 앱 유저 id
profileNickname String 프로필 닉네임
profileThumbnailImage String 프로필 썸네일 이미지 주소

아래는 offset 0과 limit 100 값으로 앱친구 목록을 조회하는 예제입니다.

public class FriendsMainActivity {
    ...

    public void requestFriends() {

        // offset = 0, limit = 100
        AppFriendContext = new AppFriendContext(true, 0, 100, "asc");

        KakaoTalkService.getInstance().requestAppFriends(friendContext,
        new TalkResponseCallback<AppFriendsResponse>() {
                    @Override
                    public void onNotKakaoTalkUser() {
                        KakaoToast.makeToast(getApplicationContext(), "not a KakaoTalk user", Toast.LENGTH_SHORT).show();
                    }

                    @Override
                    public void onSessionClosed(ErrorResult errorResult) {
                        redirectLoginActivity();
                    }

                    @Override
                    public void onNotSignedUp() {
                        redirectSignupActivity();
                    }

                    @Override
                    public void onFailure(ErrorResult errorResult) {
                        Logger.e("onFailure: " + errorResult.toString());
                    }

                    @Override
                    public void onSuccess(AppFriendsResponse result) {
                        // 친구 목록
                        Logger.e("Friends: " + result.getFriends().toString());
                        // context의 beforeUrl과 afterUrl이 업데이트 된 상태.
                    }
                });
        }
    ...   
}

페이징 처리

AppFriendContext를 사용하여 API 호출을 하게 되면 SDK에서 AppFriendsResponse의 beforeUrl과 afterUrl을 사용하여 AppFriendContext의 beforeUrl과 afterUrl을 채워주게 됩니다. 이를 사용하면 offset과 limit을 직접 조정하지 않아도 기존에 사용하였던 AppFriendContext를 재사용하여 페이징 요청을 할 수 있습니다 . AfterUrl이 존재한다면 SDK는 기존 파라미터를 사용하여 url을 만들지 않고 이 afterUrl을 사용하여 다음 페이지 요청을 하게 됩니다. 실제 호출 예제는 아래와 같습니다.

public void requestNextFriends(AppFriendContext context) {
    KakaoTalkService.getInstance().requestAppFriends(friendContext,
    new TalkResponseCallback<AppFriendsResponse>() {
                @Override
                public void onNotKakaoTalkUser() {
                    KakaoToast.makeToast(getApplicationContext(), "not a KakaoTalk user", Toast.LENGTH_SHORT).show();
                }

                @Override
                public void onSessionClosed(ErrorResult errorResult) {
                    redirectLoginActivity();
                }

                @Override
                public void onNotSignedUp() {
                    redirectSignupActivity();
                }

                @Override
                public void onFailure(ErrorResult errorResult) {
                    Logger.e("onFailure: " + errorResult.toString());
                }

                @Override
                public void onSuccess(AppFriendsResponse result) {
                    // 친구 목록
                    Logger.e("Friends: " + result.getFriends().toString());
                    // context의 beforeUrl과 afterUrl이 업데이트 된 상태. hasNext() 메소드를 통해 다음 페이지 호출 가능 여부를 판단한다.
                    if (context.hasNext()) {
                        requestNextFriends(context);
                    } else {
                        // 모든 페이지 요청 완료.
                    }

                }
            });
}

위와 같이 성공 콜백에서 다음 페이지 호출을 하기보단 유저가 RecyclerView나 ListView등을 통해 구현된 리스트를 스크롤할 시에 lazy하게 다음 페이지를 호출하는 방식으로 불필요한 API 호출을 막는 것을 추천합니다.

에러 처리

친구목록 조회 API는 카카오톡 친구 중 정보 제공 동의를 한 사용자를 내려주기 때문에 만약 해당 카카오계정이 카카오톡을 사용하고 있지 않다면 에러를 내려주게 됩니다. 위에러는 아래와 같은 방식으로 처리할 수 있습니다.

// KakaoTalkService, TalkResponseCallback를 사용할 경우
KakaoTalkService.getInstance().requestAppFriends(new 
TalkResponseCallback<AppFriendsResponse> {
    @Override
    public void onNotKakaoTalkUser() {
        // 카카오톡 사용자가 아닌 경우
        KakaoToast.makeToast(getApplicationContext(), "not a KakaoTalk user", Toast.LENGTH_SHORT).show();
    }

    ...

    @Override
    public void onFailure(ErrorResult errorResult) {
        // 그 외 에러
        Logger.e("onFailure: " + errorResult.toString());
    }

    @Override
    public void onSuccess(AppFriendsResponse result) {
        // 친구 목록
        Logger.e("Friends: " + result.getFriends().toString());
    }

});

API 사용 제약

  • 검수 전에는 별도의 개인정보 제공 동의없이 내 애플리케이션 > 설정 > 팀관리에 설정된 카카오 계정의 톡 친구들에 한해서 동작하게 됩니다.
  • 해당 API를 서비스에 적용하려면 반드시 검수를 받아야 합니다. 앱친구 API 검수 신청하기

  • 검수를 마치면 내 애플리케이션 > 설정 > 사용자 관리 > 동의항목 > 설정에서 카카오 서비스 내 친구목록 개인정보 보호항목을 설정할 수 있게 됩니다.


Last Modified : 2018-08-23