เริ่มต้นกับ Longdo Map SDK สำหรับ Android | แผนที่ Longdo Map แผนที่ประเทศไทย ใช้ง่าย ละเอียด

การใช้ Longdo Map SDK สำหรับ Android มี 2 สิ่งที่ขาดไม่ได้คือ

Longdo Map API key โดยสามารถขอผ่านหน้าเวป Longdo Map โดยใช้ ชื่อ package name ของ Application
Longdo Map Android SDK ซึ่งสามารถดาวน์โหลดไฟล์ได้ที่
- .jar (สำหรับ Eclipse) (MD5 file hash of LongdoMapAndroidSDK_v0.1.3.jar : 92bea0ef49c7e8da8ac7b8f020335e3a)
- .arr (สำหรับ Android Studio) (MD5 file hash of LongdoMapAndroidSDK_v0.1.8.aar : 52d98e8deaaef4400f2623eebb212daa)

Longdo Map API key

เข้าสู่ระบบ หรือลงทะเบียน ถ้ายังไม่เป็นสมาชิก ด้านขวาบนของหน้าเวป Longdo Map
กดลิงค์ My Longdo map ด้านบนขวาของหน้าเวป Longdo Map
กดเลือกแถบ MM Map API
ในช่อง host name ให้ใส่ชื่อ package name ของ application ที่เราจะสร้าง เช่น com.example.mm_map_android
กดปุ่ม Generate key ท่านจะได้ MM Map API Key ของท่าน (กรุณาจำชื่อ package name และ key ของท่านไว้ เนื่องจากจะต้องใช้งานในภายหลัง)

Longdo Map Android SDK

เปิดโปรแกรม Eclipse (หากท่านยังไม่เคยเขียน application Android มาก่อน สามารถเริ่มศึกษาเบื้องต้นได้)ที่นี่
Download MM Map Android SDK (.jar) ที่นี่
สร้างโปรเจคใหม่ โดยเลือก Android Application Project
ทำตามขั้นตอนที่ eclipse แนะนำไปเรื่อยๆ เมื่อเสร็จแล้วให้เลือก Finish (ต้องใช้ชื่อ package name ตามที่กำหนดไว้ตอน generate key เท่านั้น)
ทดลอง run application โดยคลิกขวาที่ project เลือก run as -> Android Application จะได้ application หน้าว่างๆ และมีข้อความ Hello World
นำ MM Map Android SDK เข้ามาในโปรเจคโดยการ Copy ไฟล์ jar ไปไว้ใน folder libs
คลิกขวาที่ไฟล์ LongdoMapAndroidSDK.jar แล้วเลือก add to build path
นำเข้า Google Play Service lib เพื่อช่วยในการค้นหาตำแหน่งโดยเลือกที่ File->import->Existing Android Code into workspace
กด browser แล้วเลือกตำแหน่งของ Google Play Service Libraly โดยปกติจะอยู่ใน {SDK LOCATION}/extras/google/google_play_services/libproject เช่น adt-bundle-linux-x86_64-20140702\sdk\extras\google\google_play_services\libproject แล้วเลือก Finish
หลังจากนำเข้า Google Play Server lib แล้ว ต้องเชื่อมโปรเจคที่เราสร้างขึ้นและ Google Play Server lib โดย คลิกขวาที่ Project ที่เราสร้าง เลือก Properties เลือกแถบ Android
กด add และเลือก google-play-services_lib เสร็จแล้วเลือก ok
เลือกไฟล์ xml ที่ต้องการแสดงแผนที่ ในตัวอย่างคือไฟล์ activity_main.xml ลบข้อความเดิมออก ในที่นี้คือ TextView ที่แสดงข้อความ Hello World

เพิ่ม View ที่ใช้แสดงแผนที่ลงไปแทน โดย View จะชื่อ com.longdo.api.MapGLSurfaceView

  <com.longdo.api.MapGLSurfaceView
         android:id="@+id/mapview"
         android:layout_width = "match_parent"
         android:layout_height = "match_parent" />

เปิดไฟล์ AndroidManifest.xml ขึ้นมา และเพิ่ม permission ของ app ไว้ก่อน tag uses-sdk ดังนี้

    <uses-feature android:glEsVersion="0x00020000" android:required="true" />
    <uses-permission android:name="android.permission.INTERNET"/>
    <uses-permission android:name="android.permission.ACCESS_NETWORK_STATE"/>
    <uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE"/>
    <uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE"/>
    <uses-permission android:name="android.permission.ACCESS_COARSE_LOCATION"/>
    <uses-permission android:name="android.permission.ACCESS_FINE_LOCATION"/>

เพิ่ม meta tag ของ Google Play Service ในไฟล์ AndroidManifest.xml เดิม ดังนี้

        <meta-data android:name="com.google.android.gms.version" android:value="@integer/google_play_services_version" />

เพิ่ม meta tag ของ Longdo Map API Key ในไฟล์ AndroidManifest.xml เหมือนข้อที่แล้ว โดยใช้ key ชื่อ longdo.map.key และแทนนี้ข้อความ REPLACE_WITH_YOUR_API_KEY ด้วย api key ที่ได้จากขั้นตอนการ generate key ดังนี้
```
<meta-data android:name="longdo.map.key" android:value="REPLACE_WITH_YOUR_API_KEY" />
```
เปิดไฟล์ .java ของ activity ที่สร้าง (ในตัวอย่างคือ MainActivity.java) แล้วให้ class MainActivity implement IMapListener สังเกตว่าจะมีการ import com.longdo.api.IMapListener; ตอนต้นของไฟล์ และหากมี Error ปรากฏ ให้เลือกให้ Eclipse จัดการ "Add Unimplemented Methods" ให้หมด
สร้างตัวแปร MapGLSurfaceView เพื่อใช้เก็บ View ของแผนที่ และเรียก method setListener เพื่อส่ง class Activity ของเราไปเป็น listener
```
  MapGLSurfaceView mapGLSurfaceView = (MapGLSurfaceView) findViewById(R.id.mapview);
  mapGLSurfaceView.setListener(this);
```
run application อีกครั้ง จะเห็นแผนที่แสดงเต็มหน้าจอ

ตัวอย่างการเพิ่ม Layer และการเปลี่ยน Base ของแผนที่โดยใช้บริการ online ของ Longdo

ไปที่ method ชื่อ onMapCreated() จะมีตัวแปร Map ส่งมาด้วย ตัวแปรนี้จะเป็นตัวแปรหลักเพื่อควบคุมการทำงานของแผนที่
การเปลี่ยน Base ของแผนที่สามารถทำได้โดยการส่งตัวแปล Layer ผ่านทาง method setBase() ของตัวแปล Map ซึ่งหากท่านต้องการใช้งาน Layer ของ Longdo สามารถสร้างตัวแปล LongdoLayer ขึ้นมาใช้งานได้เลยซึ่งจะง่ายกว่าการสร้างตัวแปร Layer ตรงๆ โดย parameter ที่รับจะเป็น Context ของ application, weight, minimum zoom level และ maximum zoom level ตามลำดับ (ค่า weight จะไม่มีผลเมื่อ Layer นั้นถูกใช้งานเป็น Base แต่จะมีผลเมื่อใช้งานเป็น Layer ซ้อนทับบนแผนที่ในตัวอย่างข้อต่อไป)ในตัวอย่างจะเปลี่ยน Base ของแผนที่เป็น mode "gray"
ซึ่งจะได้ผลลัพธ์ดังนี้
การเพิ่ม Layer ของแผนที่ สามารถทำได้แบบเดียวกับการเปลี่ยน Base แต่เปลี่ยนจากการเรียกใช้ method setBase() เป็น addLayer() โดยในตัวอย่างจะเป็นการเพิ่ม Layer แสดงพื้นที่น้ำท่วมจาก Gistda ปี 2013
ซึ่งจะได้ผลลัพธ์ดังนี้

การใช้งานแผนที่จาก Longdo Box คู่กับบริการ online ของ Longdo

การใช้งานแผนที่จาก Longdo Box จะเหมือนกับการใช้งานแผนที่จากบริการ online ของ Longdo ทุกอย่าง ยกเว้นผู้ใช้จะต้องใส่ URL ของ Longdo Box ตอนที่สร้าง Layer ด้วย โดยการทำงานจะเริ่มจากไปที่ method ชื่อ onMapCreated() และสร้าง object ของ LongdoBoxLayer โดย parameter ที่รับจะเป็น Context ของ application, url ของ LongdoBox, mode แผนที่ที่ต้องการใช้งาน, weight, minimum zoom level และ maximum zoom level ตามลำดับ (ค่า weight จะไม่มีผลเมื่อ Layer นั้นถูกใช้งานเป็น Base แต่จะมีผลเมื่อใช้งานเป็น Layer ซ้อนทับบนแผนที่ในตัวอย่างข้อต่อไป)ในตัวอย่างจะเปลี่ยน Base ของแผนที่เป็น mode "gray" (*warning ใน code ตัวอย่างเกิดจากการที่เราสร้าง object ของ LongdoBoxLayer ขึ้นมา แต่ยังไม่นำไปใช้งาน ซึ่ง warning นี้จะหายไปในขั้นตอนต่อไป)
การเปลี่ยน Base ของแผนที่สามารถทำได้โดยการส่งตัวแปล LongdoBoxLayer ที่สร้างไว้ให้กับ method setBase() ของตัวแปล Map
ซึ่งจะได้ผลลัพธ์ดังนี้
การเพิ่ม Layer ซ้อนทับโดยใช้บริการ online ของ Longdo ท่านสามารถย้อนกลับไปดูคำอธิบายได้จากหัวข้อ "ตัวอย่างการเพิ่ม Layer และการเปลี่ยน Base ของแผนที่โดยใช้บริการ online ของ Longdo" ในหัวข้อย่อยที่ 4 ในตัวอย่างนี้เราจะสร้าง Layer เส้นสีจราจรขึ้นมาซ้อนทับกับแผนที่ mode gray จาก Longdo Box
ซึ่งจะได้ผลลัพธ์ดังนี้

ขั้นตอนการใช้งานโปรเจคตัวอย่าง

ในไฟล์ zip ของตัวอย่างโปรเจค (LongdoMapSDKSample.zip) จะมี directory ชื่อ LongdoMapSDKSample ให้ท่านคัดลอกแล้วนำไปวางในเครื่อง และจำ path ที่ท่านนำไฟล์ไปวางไว้ เนื่องจากต้องใช้ในขั้นตอนการ import
ในตัวอย่างนี้ จะใช้ Eclipse เป็น IDE สำหรับการพัฒนา Application ซึ่งท่านสามารถศึกษาวิธีการติดตั้งได้ที่ Eclipse Plugin สำหรับการพัฒนา Android Application ได้ ที่นี่
เมื่อติดตั้ง Eclipse และ ADT เรียบร้อยแล้ว สิ่งที่จำเป็นต่อการ build โปรเจคตัวอย่างคือ SDK ของ API 19 (Android 4.4.2) เนื่องจากโปรเจคนี้ถูกตั้งค่าให้ใ้ช API 19 เป็นตัว build โดยขั้นตอนการตรวจสอบว่าท่านได้ติดตั้ง API 19 สามารถทำได้โดยคลิกที่ ICON "Android SDK Manager" ()
จะปรากฏหน้าต่างเพื่อจัดการ SDK ขึ้นมา ให้เลื่อนไปหา SDK ของ API 19 และเลือก package ที่ท่านต้องการติดตั้ง ซึ่งอย่างน้อยที่สุดจะต้องเลือก SDK platform และหากต้องการใช้ Emulator เพื่อพัฒนา Application ให้เลือก ไฟล์ Image ด้วย ในขั้นตอนนี้หากในเครื่องได้ติดตั้ง SDK ของ API 19 ไว้แล้ว จะมีคำว่า "Installed" อยู่ด้านหลัง (เหมือนในภาพตัวอย่างด้านล่าง) แต่หากยังไม่ได้ติดตั้ง จะเป็นคำว่า "Not installed" แทน
เมื่อเลือก package เสร็จแล้วให้กด Install packages และทำตามขั้นตอนของ wizard ต่อไปเรื่อยๆ ซึ่งจะมีขั้นตอนการ Download ไฟล์ package จาก Internet เพราะฉนั้นท่านจะต้องเชื่อมต่อเครื่องคอมพิวเตอร์ของท่านกับ Internet ก่อน
เมื่อติดตั้ง SDK และ API 19 เรียบร้อยแล้ว ต่อไปจะเป็นขั้นตอนการ import ไฟล์โปรเจคตัวอย่างเข้ามาใน Eclipse โดยเลือก File->import จะปรากฏหน้าต่างเพื่อเลือก project ที่ต้องการ import ขึ้นมา ให้เลือก Android->Existing Android Code Into Workspace และกด Next
จะมีหน้าต่าง import โปรเจคเปิดขึ้นมา ให้ท่านเลือกปุ่ม browse และเลือก directory ของโปรเจคตัวอย่างซึ่งจะใช้ชื่อว่า "LongdoMapSDKSample"
หากท่านเลือก directory ที่ถูกต้อง ที่ช่องด้านล่างจะมีโปรเจคถูกเลือกอยู่ 2 โปรเจรคือ google-play-service_lib และ LongdoMapSDKSample หากท่านไม่เห็นโปรดจคทั้ง 2 นี้ปรากฏขึ้นมา ให้ท่านตรวจสอบว่าท่านได้ download ไฟล์ตัวอย่างโปรเจคมาสมบูรณ์และได้เลือก directory ที่ถูกต้อง
เลือกทั้ง 2 โปรเจคด้วยการติ๊กเครื่องหมายถูก และกด Finish ท่านจะเห็นว่ามี Project ถูกเพิ่มเข้ามาใน workspace ของท่าน 2 โปรเจค
โปรเจคที่ถูก import เข้ามาคือโปรเจคตัวอย่างและโปรเจค google-play-service ซึ่งต่อไปจะพูดถึงเฉพาะโปรเจคตัวอย่างเท่านั้น ส่วนตัวโปรเจค google-play-service เป็นโปรเจคที่ตัว Longdo Map SDK ต้องการเพื่อช่วยในการค้นหาตำแหน่งปัจจุบันของผู้ใช้ โดยที่ท่านไม่จำเป็นต้องเข้าไปแก้ไขโค้ดใดๆ
ถึงขั้นตอนนี้ท่านสามารถทดลอง run application เพื่อนดูการทำงานของโปรเจคตัวอย่างนี้ได้ โดยคลิกขวาที่โปรเจคตัวอย่างในหน้าต่าง Package Explorer เลือก Run As -> Android Application
ข้อควรระวัง หากท่านใช้ emulator เพื่อทดสอบ run application ในขั้นตอนการสร้าง emulator ท่านจะต้องเลือกช่องที่เขียนว่า Use Host GPU ด้วย เพื่อบบอก emulator ให้ใช้ GPU ของเครื่องคอมพิวเตอร์ไม่เช่นนั้น ตัว emulator จะไม่สามารถใช้งาน OpenGL ซึ่งเป็นตัววาดแผนที่ได้ และหากท่านต้องการทดสอบความสามารถในการเก็บ cache แผนที่ ท่านต้องใส่ขนาดของ SD card จำลองให้ emulator ด้วย (ในตัวอย่างใส่ค่าไว้ 512 MB)
รายการ feature ที่ติดมากับโปรเจคตัวอย่างมีดังนี้:
1. แสดงแผนที่ Longdo Map ใน mode "ICONS" เป็น base
2. เปลี่ยน base แผนที่เป็น Longdo Map ใน mode "Gray"
3. เพิ่ม Layer พื้นที่น้ำท่วมจาก Gistda ปี 2013
4. Zoom เข้า/ออก โดยใช้ปุ่มสั่งงาน
5. ปักหมุด/เพิ่มเส้นบนแผนที่
6. ระบุตำแหน่งปัจจุบันของผู้ใช้
7. ลบ cache ภาพแผนที่ในเครื่อง
8. feature พื้นฐานอื่นๆ ของแผนที่ เช่น double tap เพื่อ zoom เข้า, ใช้สองนิ้วแตะเพื่อ zoom ออก, pinch zoom เป็นต้น
รายละเอียด feature อื่นๆ สามารถเปิดดูได้จาก SDK Document