ODsay SDK 설정 가이드(ODsay SDK Setup Guide)

ODsay SDK for Android 연결 방법(Android Studio 기준)(Connect method to ODsay SDK for Android)

•Tool bar

File -> Project Structure


New Module 클릭


Import .JAR/.AAR Package 선택 및 Next

File name, Subproject name 필드에 다운로드 받으신 ODsayAndroidSDK 라이브러리 파일 경로 및 모듈명 설정


ODsayAndroidSDK 추가 확인 및 Gradle build


File -> Project Structure


메인 모듈의 Dependencies 창에서 Module Dependency 클릭


ODsayAndroidSDK 모듈 추가

Gradle 설정(Gradle Settings)

•Android SDK 버전 4.1(젤리빈/API Level 16)이상

AndroidManifast.xml 에서 SDK 정보를 명시 할 경우 :

코드
<uses-sdk android:minSdkVersion=”16”
	android:targetSdkVetsion=”[integer]” />
	

build.gradle 에서 SDK 정보를 명시 할 경우 :

코드
android {
	defaultConfig {
		minSdkVersion 16
		targetSdkVersion [integer]
	}
}
 

※ Gradle, AndroidManifast 모두 SDK 정보가 명시 되어 있을 경우 Gradle(기본 빌드)를 우선으로 합니다.

코드
dependencies {
	compile ‘com.google.code.findbugs:jsr305:2.0.1’
}
 

•JAVA 버전 최소 7 이상

컴파일 시 문제가 발생한다면 build.gradle 에서 다음과 같이 컴파일 레벨을 잡아줍니다.(Java 7 설치 기준)

코드
android {
	compileOptions {
		sourceCompatibility JavaVersion.VERSION_1_7
		targetCompatibility JavaVersion.VERSION_1_7
	}
}
 

프로가드 적용 방안(Apply ProGuard)

프로가드가 다음과 같이 설정 되었을 경우 룰에 다음과 같이 추가

// 프로가드 설정 부분
release {
	minifyEnabled true
	proguardFiles getDefaultProguardFile(‘proguard-android.txt’),
	‘proguard-rules.pro’
}
// ‘proguard-rules.pro’ 파일에 SDK 프로가드 예외 처리 추가
-keep interface com.odsay.odsayandroidsdk.**{*j}
 

적용 디바이스별 API Level(API Level by Device)

2017.09 기준으로 작성된 목록 입니다.

ODsay SDK API 가이드(ODsay SDK API Guide)

ODsay SDK는 API 호출 메서드, 비동기 통신 기능 등을 포함하여 개발자들이 보다 쉽고 간편하게 사용할 수 있도록 편의를 제공합니다.

API 항목(API List)

API 활용 예시(API Usage Example)

• 파라미터 규칙

모든 API에는 1개의 파라미터가 공통으로 존재하며, 그 목록은 아래와 같습니다.

각 API별 파라미터에는 필수(필수값 : Y) 파라미터와 선택적인(필수값 : N) 파라미터가 존재하며, 선택적 파라미터를 기재하지 않아도 자동으로 default값이 입력됩니다. (default 값은 각 API별 레퍼런스 페이지에서 확인 가능합니다.)

버스노선 조회 API의 파라미터 규칙은 아래와 같습니다.

각각의 API 파라미터는 레퍼런스에서 확인 가능합니다.

•API 호출 방법

ODsaySDK 는 ODsayService 객체를 만들어 사용합니다. ODsayService는 싱글톤 객체로 생성 됩니다.

odsayService.init(Context context, String apiKey)
	//‘ODsayService’ 객체 생성시 사용합니다.
	
odsayService.setConnectionTimeout(int connetionTimeout)
	//서버 연결 제한 시간 설정합니다.(default : 5초, 단위 : millisecond )
	
odsayService.setReadTimeout(int readTimeout)
	//데이터 획득 제한 시간 설정합니다.(default : 5초, 단위 : millisecond )
	
odsayService.requestSearchBusLane(param1, param2..., OnResultCallbackListener())
	//API 호출을 실행하고 OnResultCallbackListener 을 통해 결과를 반환 받습니다.
	

•API 호출 콜백 함수 정의

코드
OnResultCallbackListener() {
	@Override
	public void onSuccess(ODsayData odsayData, API api) {}

	@Override
	public void onError(int code, String message, API api) {}
}
 

호출 성공 시 onSuccess(ODsayData odsayData, API api) 호출
   - odsayData : API 호출 결과 데이터를 리턴합니다. Json, Map 형식의 데이터 서비스를 제공하고,
   getJson, getMap 메서드를 통해 가져옵니다.
   - api : 호출한 API 값 종류를 리턴합니다. API명은 호출 메서드 네이밍을 따라갑니다.
호출 실패 시 onError(int code, String message, API api) 호출 :
   - code : 에러 코드 값을 리턴합니다.
   - message : 에러 메시지를 리턴합니다.
   - api : 호출한 API 값 종류를 리턴합니다.

•API 호출 방법사용 예제

코드
import com.odsay.odsayandroidsdk.API;
import com.odsay.odsayandroidsdk.ODsayData;
import com.odsay.odsayandroidsdk.ODsayService;
import com.odsay.odsayandroidsdk.OnResultCallbackListener;

@Override
protected void onCreate(Bundle savedInstanceState) {
	// 싱글톤 생성, Key 값을 활용하여 객체 생성
	ODsayService odsayService = ODsayService.init(Context, {발급받은 키값});
	// 서버 연결 제한 시간(단위(초), default : 5초)
	odsayService.setReadTimeout(5000);
	// 데이터 획득 제한 시간(단위(초), default : 5초)
	odsayService.setConnectionTimeout(5000);

	// 콜백 함수 구현
	OnResultCallbackListener onResultCallbackListener = new OnResultCallbackListener() {
		// 호출 성공 시 실행
		@Override
		public void onSuccess(ODsayData odsayData, API api) {
			try {
				// API Value 는 API 호출 메소드 명을 따라갑니다.
				if (api == API.BUS_STATION_INFO) {
					String stationName = odsayData.getJson().getJSONObject("result").getString("stationName");
					Log.d(“Station name : %s”, stationName);
				}
			}catch (JSONException e) {
				e.printStackTrace();
			}
		}
		// 호출 실패 시 실행
		@Override
		public void onError(int i, String s, API api) {
			if (api == API.BUS_STATION_INFO) {}
		}
	};
	// API 호출
	odsayService.requestBusStationInfo(“107475”, onResultCallbackListener());
}
 

에러 코드는 아래와 같습니다.

ODsay SDK Sample 가이드(ODsay SDK Sample Guide)

ODsay SDK for Android Sample 프로젝트를 다운받습니다.(Download the ODsay SDK for Android)

ODsay SDK for Android Sample은 SDK 다운로드에서 함께 다운받을 수 있습니다.

샘플 프로젝트에 앱 등록 시 발급 되는 API Key 값을 입력 해야 합니다.(Enter the API Key)

string.xml 파일에서 “odsay_key” 리소스 값의 API KEY 부분에 본인의 키를 넣어줍니다.

코드
<resources>
	<string name=”app_name”>ODsayAndroidSDKSample</string>
	<string name=”odsay_key”>API KEY</string>
</resources>
 

※ string.xml 경로 : Project / app / src / main / res / values / string.xml

프로젝트의 build.gradle 파일에 자신의 패키지로 변경합니다.(Change the package)

applicationId에 {패키지명} 변경합니다.

...
    defaultConfig {
        applicationId "com.odsay.odsayandroidsdksample"
        minSdkVersion 16
        targetSdkVersion 26
        versionCode 1
        versionName "1.0"
        testInstrumentationRunner "android.support.test.runner.AndroidJUnitRunner"
    }
...
		

※ 경로 : ODsayAndroidSDKSample > build.gradle

src 폴더구조를 자신의 패키지에 맞게 변경 합니다.(Change the src folder structure)

package는 폴더 구조로 되어 있습니다. "."을 기준으로 폴더를 만듭니다.

androidManifest.xml에 자신의 package로 변경합니다.(Change the package in androidManifest.xml)

Manifest 태그의 package="{패키지}”를 자신의 package로 변경합니다.

...
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
          package="com.odsay.odsayandroidsdksample">
    <uses-permission android:name="android.permission.INTERNET" />
​...
		

실시간 도착정보 연동 가이드(Real-time Arrival Information Linking Guide)

ODsay API는 공공데이터포탈(https://www.data.go.kr/) 에서 제공하는 오픈API와 연동하여 실시간 데이터를 제공할 수 있습니다. 오픈 API는 제공사이트마다 사용방법이 상이하며 각 사이트의 가이드를 참조하시기 바랍니다. 이 가이드는 공공데이터포탈 API를 ODsay API와 연동하여 서울시의 실시간 데이터를 활용하는 예시입니다. 타 지역은 하단의 참고사항에서 확인하시길 바랍니다.

공공데이터포탈 일부 API의 경우 CORS 정책으로 인해 서버 단에서 API를 호출해야 합니다.
크로스도메인 관련 참고자료 : 공공데이터포탈 자료실

ODsay API 호출(ODsay API Call)

ODsay API를 호출하여 얻은 결과값의 특정 데이터값을 오픈 API를 호출하기 위한 파라미터 값으로 넘겨주어 연동함으로써 실시간 데이터를 이용할 수 있습니다. 대중교통 정류장 검색 API를 이용하여 정류소을 검색하면 아래와 같은 결과를 얻을 수 있습니다.


위의 결과는 파라미터 값으로 stationName에 "당산유원제일1차아파트"를 입력한 결과 값 입니다. 여기서 arsID를 획득할 수 있습니다.

오픈 API 호출(Open API Call)

공공데이터포탈(https://www.data.go.kr/) 의 가이드를 참조하여 키를 발급받은 후, 필요한 API를 검색하여 신청합니다.
신청한 API의 상세정보 하단에 해당 API를 호출하는 예시를 언어별로 제공합니다.

원하는 언어에 발급받은 키와 파라미터를 입력하여 API를 호출하면 실시간정보를 얻을 수 있습니다.

아래는 서울특별시에서 제공하는 정류소정보조회 서비스 중 getStationByUidItem API의 Java 소스 예시 입니다.
API를 호출하는 코드 중 통신을 하기위한 URI과 파라미터값을 설정하는 부분입니다.

public class GetStationByUid{
.
.                            	
String SERVICE_KEY = "서비스 키";
String URL = "http://ws.bus.go.kr/api/rest/stationinfo/getStationByUid";
StringBuilder urlBuilder = new StringBuilder(URL);
urlBuilder.append("?" + URLEncoder.encode("ServiceKey", "UTF-8")+"="+SERVICE_KEY);
urlBuilder.append("&" + URLEncoder.encode("arsId", "UTF-8") + "=" + URLEncoder.encode("arsID값", "UTF-8"));
.
.                      	
										

파라미터 값으로 arsID(정류소번호)에 ODsay API에서 획득한 데이터 '19-182' 를 오픈 API의 파라미터 형식에 맞게 '19182'로 문자열을 가공한 뒤 입력하고 API를 호출하면 해당 정류장의 실시간 도착정보를 조회할 수 있습니다.

결과
<ServiceResult>
	<comMsgHeader/>
	<msgHeader>
		<headerCd>0</headerCd>
		<headerMsg>정상적으로 처리되었습니다.</headerMsg>
		<itemCount>0</itemCount>
	</msgHeader>
	<msgBody>
		<itemList>
			<adirection>신도림역</adirection>
			<arrmsg1>5분11초후[1번째 전]</arrmsg1>
			<arrmsg2>14분2초후[7번째 전]</arrmsg2>
			<arrmsgSec1>5분11초후[1번째 전]</arrmsgSec1>
			<arrmsgSec2>14분2초후[7번째 전]</arrmsgSec2>
			<arsId>19182</arsId> 
			.
			.
			.
			<rtNm>영등포12</rtNm>
			.
			.
		</itemList>
		<itemList>
		.
		.
		</itemlist>
	</msgBody>
</ServiceResult>
	                            

위의 결과는 ODsay API의 'arsID'를 이용하여 정류소의 실시간 버스도착정보를 호출한 결과값 입니다.

ODsay API의 데이터와 그 데이터를 이용해 호출한 오픈 API의 데이터를 활용해 필요한 정보를 추출하고 제공하는 실시간 서비스를 아래와 같이 만들 수 있습니다.


실제 ODsay API 호출 결과와 오픈 API 호출 결과를 조합한 예시 입니다.

참고사항(Note)

공공데이터포탈에서 실시간 도착정보 API 사용 시, 아래의 지역별 API 파라미터를 참고하길 바랍니다.

공공데이터포탈에서 실시간 도착정보 API를 지원하지 않는 지역의 실시간 도착정보 연동은 불가능합니다.

다국어 API 적용 가이드(Multilingual API Guide)

영문, 중문(간체,번체), 일문 등 다국어를 제공하고 있으며 API 파라미터에 원하는 언어의 파라미터 값을 추가하는 것만으로 번역된 API 서비스를 사용하실 수 있습니다. 현재 다국어는 체험기간으로 국문과 함께 2018년 3월 30일까지 무료로 제공됩니다. 체험기간 이후 다국어는 유료 서비스로 제공되며 추후 가격정책과 함께 공지될 예정입니다. (ODsay SDK는 다국어 추후 제공 예정)

언어별 파라미터 값(Parameter Values by Language)

국문, 영문, 일문, 중문(간체), 중문(번체)은 서로 다른 파라미터 값을 가지고 있습니다.

상표사용가이드(Trademark Usage Guide)

다음의 가이드는 ODsay API를 이용해 개발한 서비스에서 ODsay 브랜드의 가치와 권리를 지키고자 안내하고 있으며, 모든 조항을 준수하면 사전허가 절차없이 상표를 사용할 수 있습니다.

ODsay BI

↓ 다운로드

1) 이용자는 ODsay API를 이용하여 개발한 서비스에서 아래와 같은 위치에 상표를 표시하여 권리 귀속문구를 사용해야 합니다.

• ODsay API를 이용하여 개발한 상품 또는 서비스 내 대중교통 컨텐츠에 대한 설명, 소개페이지
• ODsay API를 이용하여 개발한 상품 또는 서비스에 대중교통 정보가 노출되는 결과페이지
• 기타 ODsay API와 관계되어 설명이 필요한 상품 또는 서비스 내 형식에 맞게 노출

활용예시(Example)

아래 이미지 또는 텍스트로 표기하며 텍스트는 시스템폰트나 기본폰트를 사용합니다.

↓ 다운로드 powered by www.ODsay.com Text Type 복사

• 웹 서비스 Image Type Text Type

• 앱 서비스 Image Type Text Type

2) 이용자는 ODsay 상표를 수정 혹은 변형하거나, 다른 상표와 결합 혹은 조합하여 사용하면 안됩니다.

3) ODsay API를 이용하여 개발한 애플리케이션의 이름, 아이콘을 비롯하여 상품명, 서비스명, 회사명, 로고, 심볼 등에 ODsay의 상표를 사용하면 안됩니다.

4) 그 밖에 애플리케이션의 내부, 마켓, 웹페이지, 기타 광고물 등에 ODsay 상표의 식별력이나 명성을 손상할 가능성이 있는 아래의 예와 같은 사용도 허용이 되지 않습니다.

• ODsay의 상표를 보통명사처럼 사용하는 행위
• 성인컨텐츠를 제공하는 상품 또는 서비스에 ODsay의 상표를 표시하는 행위
• 도박 관련 상품 또는 서비스에 ODsay의 상표를 표시하는 행위
• ODsay의 명예 또는 타인의 명예를 훼손, 침해, 비방, 손상하는 상품 또는 서비스에 ODsay의 상표를 표시하는 행위
• 기타 관련 법을 위반하는 상품 또는 서비스에 ODsay의 상표를 표시하는 행위

5) 이용자가 직접 혹은 제3자를 통해 ODsay 및 ODsay 서비스의 명성을 훼손하거나 영업권에 손상을 줄 수 있는 경우, 이용자 혹은 제3자는 어떠한 ODsay 상표도 사용할 수 없습니다.

URI 인코딩가이드(URI Encoding Guide)

URI는 ASCII문자를 사용하여 전송할 수 있으며, 특수문자의경우 다른의미를 갖기때문에 유효한 ASCII형식으로 변환되어야합니다.
apiKey는 보안정책상 특수문자를 포함하기 때문에 직접 또는 JavaScript에서 encodeURI() 함수를 통하여 변환할 수 있습니다.

인코딩 변환 값(Encoding Conversion Value)

apiKey에 특수문자가 포함된경우 아래와같이 변환하여 요청해주시기 바랍니다.