{"id":15107799,"url":"https://github.com/vkcom/vk-java-sdk","last_synced_at":"2025-05-16T17:09:20.368Z","repository":{"id":10612493,"uuid":"64755572","full_name":"VKCOM/vk-java-sdk","owner":"VKCOM","description":"Java library for working with VK API","archived":false,"fork":false,"pushed_at":"2024-06-26T11:46:11.000Z","size":4509,"stargazers_count":294,"open_issues_count":96,"forks_count":154,"subscribers_count":41,"default_branch":"master","last_synced_at":"2025-05-16T17:08:40.378Z","etag":null,"topics":["api","java","vk"],"latest_commit_sha":null,"homepage":"","language":"Java","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/VKCOM.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"contributing.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":".github/CODEOWNERS","security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2016-08-02T12:38:34.000Z","updated_at":"2025-05-16T15:56:53.000Z","dependencies_parsed_at":"2024-12-27T12:01:03.791Z","dependency_job_id":null,"html_url":"https://github.com/VKCOM/vk-java-sdk","commit_stats":{"total_commits":434,"total_committers":30,"mean_commits":"14.466666666666667","dds":0.3709677419354839,"last_synced_commit":"3be91e5f2ab52133897e67f4b53379ee180d865a"},"previous_names":[],"tags_count":45,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VKCOM%2Fvk-java-sdk","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VKCOM%2Fvk-java-sdk/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VKCOM%2Fvk-java-sdk/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/VKCOM%2Fvk-java-sdk/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/VKCOM","download_url":"https://codeload.github.com/VKCOM/vk-java-sdk/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254573589,"owners_count":22093731,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api","java","vk"],"created_at":"2024-09-25T21:41:40.125Z","updated_at":"2025-05-16T17:09:20.322Z","avatar_url":"https://github.com/VKCOM.png","language":"Java","readme":"## Java SDK for VK API\n\n[![Build Status](https://travis-ci.org/VKCOM/vk-java-sdk.svg?branch=master)](https://travis-ci.org/VKCOM/vk-java-sdk)\n\nJava library for VK API interaction, includes OAuth 2.0 authorization and API methods. Full VK API features documentation can be found [here](http://vk.com/dev).\n\nThis library has been created using the VK API JSON Schema. It can be found [here](https://github.com/VKCOM/vk-api-schema). It uses VK API [version](https://vk.com/dev/versions) 5.199.\n\n## 1. Prerequisites\n\n* [Java JDK](http://www.oracle.com/technetwork/java/javase/downloads/index.html) 15 or later\n* [Gradle](https://gradle.org/) 7.4.2 or later\n\n## 2. Dependencies\n\nVK Java SDK uses:\n* [Apache Http Client](https://hc.apache.org) version 4.5.13\n* [SLF4J](http://www.slf4j.org/) version 2.0.9\n* [Apache Commons Lang](https://commons.apache.org/proper/commons-lang/) version 3.6\n* [Apache Commons Collections](https://commons.apache.org/proper/commons-collections/) version 4.4\n* [Apache Commons IO](https://commons.apache.org/proper/commons-io/) version 2.11.0\n* [Google Gson](https://github.com/google/gson) version  2.9.0\n\n## 3. Latest release\n\nLatest version: [![Maven](https://img.shields.io/maven-central/v/com.vk.api/sdk.svg)](http://search.maven.org/#search%7Cga%7C1%7Cg%3A%22com.vk.api%22%20AND%20a%3A%22sdk%22)\n\nTo add a dependency on VK Java SDK using Maven, use the following:\n\n```xml\n\u003cdependency\u003e\n  \u003cgroupId\u003ecom.vk.api\u003c/groupId\u003e\n  \u003cartifactId\u003esdk\u003c/artifactId\u003e\n  \u003cversion\u003eLATEST_VERSION\u003c/version\u003e\n\u003c/dependency\u003e\n```\n\nTo add a dependency using Gradle:\n\n```\ndependencies {\n  compile 'com.vk.api:sdk:LATEST_VERSION'\n}\n```\n\n## 4. Prepare for using\n\nCreate a new VK application [here](https://vk.com/editapp?act=create) to use VK Java SDK. Please choose an application type depending on which authorization pattern you need. It should be \"Standalone\" for Direct Authorization, \"Web site\" for Authorization Code Flow for  server side  requests and any of them for Client Credentials Flow. \n\nFill in the title, confirm the action via SMS and you will be redirected to the application settings page. \n\nYou will need your application ID (referenced as API_ID in the documentation), secure key (CLIENT_SECRET) and authorized redirect URI (REDIRECT_URI).\n\n## 5. Logging\n\nVK Java SDK uses SLF4J for logging. If you want to turn on logging, you must include a plugin that bridges SLF4J with a concrete logging framework. See [SLF4J documentation](http://www.slf4j.org/manual.html#swapping).\n\n### JDK Logger\n\nMaven:\n```xml\n\u003cdependencies\u003e\n    \u003cdependency\u003e\n        \u003cgroupId\u003eorg.slf4j\u003c/groupId\u003e\n        \u003cartifactId\u003eslf4j-api\u003c/artifactId\u003e\n        \u003cversion\u003e2.0.9\u003c/version\u003e\n    \u003c/dependency\u003e\n\u003c/dependencies\u003e\n```\n\nGradle:\n```\ndependencies {\n    compile group: 'org.slf4j', name: 'slf4j-api', version: '2.0.9'\n}\n```\n\nAdd logging.properties file with configuration (located at your src/main/resources path):\n```\n.level=INFO\nhandlers=java.util.logging.ConsoleHandler\njava.util.logging.ConsoleHandler.level=FINEST\ndeng.level=FINEST\n```\n\nSet java.util.logging.config.file system property:\n```\n-Djava.util.logging.config.file=logging.properties\n```\n\n### log4j2\n\nMaven:\n```xml\n\u003cdependencies\u003e\n    \u003c!-- Binding for Log4J --\u003e\n    \u003cdependency\u003e\n      \u003cgroupId\u003eorg.apache.logging.log4j\u003c/groupId\u003e\n      \u003cartifactId\u003elog4j-slf4j-impl\u003c/artifactId\u003e\n      \u003cversion\u003e2.20.0\u003c/version\u003e\n    \u003c/dependency\u003e\n    \n    \u003c!-- Log4j API and Core implementation required for binding --\u003e\n    \u003cdependency\u003e\n      \u003cgroupId\u003eorg.apache.logging.log4j\u003c/groupId\u003e\n      \u003cartifactId\u003elog4j-api\u003c/artifactId\u003e\n      \u003cversion\u003e2.20.0\u003c/version\u003e\n    \u003c/dependency\u003e\n    \u003cdependency\u003e\n      \u003cgroupId\u003eorg.apache.logging.log4j\u003c/groupId\u003e\n      \u003cartifactId\u003elog4j-core\u003c/artifactId\u003e\n      \u003cversion\u003e2.20.0\u003c/version\u003e\n    \u003c/dependency\u003e\n\u003c/dependencies\u003e\n```\n\nGradle:\n```\ndependencies {\n    //Binding for Log4J --\u003e\n    compile group: 'org.apache.logging.log4j', name: 'log4j-slf4j-impl', version: '2.20.0'\n    \n    //Log4j API and Core implementation required for binding\n    compile group: 'org.apache.logging.log4j', name: 'log4j-api', version: '2.20.0'\n    compile group: 'org.apache.logging.log4j', name: 'log4j-core', version: '2.20.0'\n}\n```\n\nAdd log4j2.xml file with configuration (located at your src/main/resources path):\n```xml\n\u003c?xml version=\"1.0\" encoding=\"UTF-8\" ?\u003e\n\u003cConfiguration status=\"info\"\u003e\n    \u003cAppenders\u003e\n        \u003cConsole name=\"Console\" target=\"SYSTEM_OUT\"\u003e\n            \u003cPatternLayout pattern=\"%d{yyyy-MM-dd HH:mm:ss} %-5p %c{1}:%L - %m%n\"/\u003e\n        \u003c/Console\u003e\n    \u003c/Appenders\u003e\n\n    \u003cLoggers\u003e\n        \u003cRoot level=\"info\"\u003e\n            \u003cAppenderRef ref=\"Console\"/\u003e\n        \u003c/Root\u003e\n    \u003c/Loggers\u003e\n\u003c/Configuration\u003e\n```\n\n## 6. Initialization\n\nCreate VkApiClient object using the following code:\n\n```java\nTransportClient transportClient = new HttpTransportClient();\nVkApiClient vk = new VkApiClient(transportClient);\n```\n\nNote that you can use your own  transport client. We use [Apache Http Client](https://hc.apache.org/).\n\n## 7. Authorization\n\nThe library provides several authorization flows based on OAuth 2.0 protocol implementation in vk.com API. Please read the full [documentation](https://vk.com/dev/access_token) before you start.\n\n### 7.1. Authorization Code Flow for User\n\nOAuth 2.0 Authorization Code Flow allows calling methods from the server side.\n\nThis flow includes two steps — obtaining an authorization code and exchanging the code for an access token. Primarily you should obtain the \"code\" ([manual](https://vk.com/dev/authcode_flow_user)) and then use this method to complete the flow:\n\n```java\nUserAuthResponse authResponse = vk.oAuth()\n    .userAuthorizationCodeFlow(APP_ID, CLIENT_SECRET, REDIRECT_URI, code)\n    .execute();\n\nUserActor actor = new UserActor(authResponse.getUserId(), authResponse.getAccessToken());\n```\n\nThis takes your application ID, secure key, redirect URI, enumerated [scopes](https://vk.com/dev/permissions) and code obtained on the previous step of the flow.\n\nWhen succeed, a UserActor object is created. You can call VK API methods on behalf of a user.\n\n### 7.2. Authorization Code Flow for Community\n\nThe difference from the previous flow is that you send the groupId parameter to obtain the community's access token. Please read [the full manual](https://vk.com/dev/authcode_flow_group).\n\n```java\nGroupAuthResponse authResponse = vk.oAuth()\n    .groupAuthorizationCodeFlow(APP_ID, CLIENT_SECRET, REDIRECT_URI, code)\n    .execute();\n\nGroupActor actor = new GroupActor(groupId, authResponse.getAccessTokens().get(groupId));\n```\n\nWhen succeed, a GroupActor object is created. You can call VK API methods on behalf of a community.\n\n### 7.3. Handling need_validation error\n\nProceeding each of previous authorization flows you can receive a \"need_validation\" error. Use the following code to handle the error:\n\n```java\nUserAuthResponse authResponse;\ntry {\n    authResponse = vk.oAuth()\n        .userAuthorizationCodeFlow(APP_ID, CLIENT_SECRET, REDIRECT_URI, code)\n        .execute();\n} catch (OAuthException e) {\n    e.getRedirectUri();\n}\n\nUserActor actor = new UserActor(authResponse.getUserId(), authResponse.getAccessToken());\n```\n\n### 7.4. Client Credentials Flow\n\nThis flow allows to interact with API service methods with \"secure\" prefix. Use this method:\n\n```java\nServiceClientCredentialsFlowResponse authResponse = vk.oAuth()\n    .serviceClientCredentialsFlow(APP_ID, CLIENT_SECRET)\n    .execute();\n    \nServiceActor actor = new ServiceActor(APP_ID, authResponse.getAccessToken());\n```\n\nWhen succeed, a ServiceActor object is created. You can call VK API methods on behalf of an app.\n\n## 8. API Requests\nYou can find the full list of VK API methods [here](https://vk.com/dev/methods).\n\n### Request sample\n\n```java\nGetResponse getResponse = vk.wall().get(actor)\n    .ownerId(1)\n    .count(100)\n    .offset(5)\n    .filter(\"owner\")\n    .execute();\n```\n\n### Request sample with common method parameters:\n\n```java\nList\u003cUserXtrCounters\u003e users = vk.users().get(actor)\n    .userIds(\"1\")\n    .fields(UserField.VERIFIED, UserField.SEX)\n    .lang(Lang.EN)\n    .execute();\n```\n\nThe full list of common parameters is available on [this page](https://vk.com/dev/api_requests).\n\n### Request sample for uploading and posting photos on user wall.\n\n```java\nPhotoUpload serverResponse = vk.photos().getWallUploadServer(actor).execute();\nWallUploadResponse uploadResponse = vk.upload().photoWall(serverResponse.getUploadUrl(), file).execute();\nList\u003cPhoto\u003e photoList = vk.photos().saveWallPhoto(actor, uploadResponse.getPhoto())\n     .server(uploadResponse.getServer())\n     .hash(uploadResponse.getHash())\n     .execute();\n\nPhoto photo = photoList.get(0); \nString attachId = \"photo\" + photo.getOwnerId() + \"_\" + photo.getId();\nGetResponse getResponse = vk.wall().post(actor)\n    .attachments(attachId)\n    .execute();\n```\n\n## 9. Execute requests\nYou can find more information about execute method [here](https://vk.com/dev/execute).\n\n### Code\n\n```java\nJsonElement response = vk.execute().code(actor, \"return API.wall.get({\\\"count\\\": 1})\")\n    .execute();\n```\n\n### Storage function\n\n```java\nJsonElement response = vk.execute().storageFunction(actor, \"foo\")\n    .funcV(2) // set storage function version\n    .unsafeParam(\"user_id\", 1) // set storage function argument\n    .execute();\n```\n\n### Batch requests\n\n```java\nJsonElement response = vk.execute().batch(actor,\n        vk.database().getChairs(1).count(10),\n        vk.database().getCities(1),\n        vk.groups().getMembers(actor).groupId(groupId)\n).execute();\n```\n\n## 10. Error Handling\n\n### Common Example\n```java\ntry {\n    vk.wall().post(actor)\n        .message(\"Hello world\")\n        .execute();\n} catch (ApiWallLinksForbiddenException e) {\n    // Links posting is prohibited\n} catch (ApiException e) {\n    // Business logic error\n} catch (ClientException e) {\n    // Transport layer error\n}\n```\n\n### Captcha error handling\n```java\nString captchaSid = null;\nString captchaImg = null;\n\ntry {\n    vk.wall().post(actor).message(\"Hello world\").execute();\n} catch (ApiCaptchaException e) {\n    captchaSid = e.getCaptchaSid();\n    captchaImg = e.getCaptchaImg();\n}\n\n//Showing captcha image...\n\nif (captchaImg != null) {\n    vk.wall().post(actor)\n        .message(\"Hello world\")\n        .captchaSid(captchaSid)\n        .captchaKey(captchaKey)\n        .execute();\n}\n```\n\n## 11. Callback API handler\nOverride methods from CallbackApi class for handling events\n\n```java\npublic class CallbackApiHandler extends CallbackApi {\n  @Override\n  public void messageNew(Integer groupId, Message message) {\n    System.out.println(message.getText());\n  }\n}\n```\n\n## 12. Callback API Long Poll handler\nEnable Callback API Long Poll for needed group and specify\nwhich events should be tracked\n\n```java\nHttpTransportClient httpClient = HttpTransportClient.getInstance();\nVkApiClient vk = new VkApiClient(httpClient);\nvk.groups().setLongPollSettings(groupActor).enabled(true)\n                                           .wallPostNew(true)\n                                           .messageNew(true)\n                                           .execute();\n```\n\n(WIP)\nOverride methods from CallbackApiLongPoll class for handling events and create needed constructors\n\n```java\npublic class CallbackApiLongPollHandler extends CallbackApiLongPoll {\n    public CallbackApiLongPollHandler(VkApiClient client, UserActor actor, Integer groupId) {\n      super(client, actor, groupId);\n    }\n\n    public CallbackApiLongPollHandler(VkApiClient client, GroupActor actor) {\n      super(client, actor);\n    }\n\n    @Override\n    public void messageNew(Integer groupId, Message message) {\n      System.out.println(\"messageNew: \" + message.toString());\n    }\n\n    @Override\n    public void wallPostNew(Integer groupId, WallPost wallPost) {\n      System.out.println(\"wallPostNew: \" + wallPost.toString());\n    }\n}\n```\n\nIn order to use the created ```CallbackApiLongPollHandler``` which overrides methods from CallBackApiLongPoll,\nthe instance of it needs to be created and method ```run``` called\n\n```java\nCallbackApiLongPollHandler handler = new CallbackApiLongPollHandler(vk, groupActor);\nhandler.run();\n```\n\n## 13. Streaming API\n\n### Initialization\n```java\n//Init clients\nTransportClient transportClient = new HttpTransportClient();\n\nVkApiClient vkClient = new VkApiClient(transportClient);\nVkStreamingApiClient streamingClient = new VkStreamingApiClient(transportClient);\n\n//Create service actor\nInteger appId = 4123123;\nString accessToken = \"sadf0asdf0asdfsadfassadf0asdf0asdfsadfassadf0asdf0asdfsadfas\";\nServiceActor actor = new ServiceActor(appId, accessToken);\n\n//Get streaming actor\nGetServerUrlResponse getServerUrlResponse = vkClient.streaming().getServerUrl(actor).execute();\nStreamingActor actor = new StreamingActor(getServerUrlResponse.getEndpoint(), getServerUrlResponse.getKey());\n```\n\n### Add rule\n```java\n//Create rule\nString tag = \"1\";\nString value = \"ok\";\n\nStreamingResponse response = streamingClient.rules().add(actor, tag, value).execute();\n```\n\n### Get rules\n```java\n//Get rules\nStreamingGetRulesResponse response = streamingClient.rules().get(actor).execute();\n```\n\n### Delete rule\n```java\n//Delete rule\nString tag = \"1\";\nstreamingClient.rules().delete(actor, tag).execute();\n```\n\n### Stream handler\nImplement handle method from StreamingEventHandler class for handling stream events\n\n```java\nstreamingClient.stream().get(actor, new StreamingEventHandler() {\n    @Override\n    public void handle(StreamingCallbackMessage message) {\n        System.out.println(message);\n    }\n}).execute();\n```\n\n## 14. Usage Example\nAs an SDK usage example we have released the YouTrack bot. The documentation can be found [here](https://github.com/VKCOM/vk-java-sdk/wiki/YouTrack-bot).\n","funding_links":[],"categories":[],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvkcom%2Fvk-java-sdk","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fvkcom%2Fvk-java-sdk","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fvkcom%2Fvk-java-sdk/lists"}