मोड़-दर-मोड़ के निर्देश देने वाला डेटा फ़ीड, उन डिवाइसों पर सिर्फ़ नेविगेशन की जानकारी देता है जिन्हें मैप पर नेविगेशन के निर्देश देने के लिए डिज़ाइन नहीं किया गया है. यह आपके दिए गए एलिमेंट के साथ, आने वाले समय में होने वाले बदलावों की जानकारी देता है:

• आइकॉन (बाईं ओर, दाईं ओर, यू-टर्न)
• राउंडअबाउट में टर्न की संख्या
• सड़कों के नाम
• नेविगेशन के अगले चरण या आखिरी मंज़िल तक पहुंचने में लगने वाला अनुमानित समय और दूरी

टर्न-बाय-टर्न फ़ीड का इस्तेमाल करके, ऐसे अनुभव बनाए जा सकते हैं जहां नेविगेशन SDK टूल का पूरा यूज़र इंटरफ़ेस (यूआई) सही न हो. जैसे, Android Auto या छोटी स्क्रीन वाले डिसप्ले के लिए, जहां पूरा Android स्टैक उपलब्ध न हो. उदाहरण के लिए, इसका इस्तेमाल दोपहिया वाहन चलाने वालों के लिए किया जा सकता है. इसमें सिर्फ़ नेविगेशन से जुड़े निर्देश दिखाए जा सकते हैं, ताकि वे कम से कम रुकावटों के साथ, तेज़ी से और ज़्यादा भरोसे के साथ अपने डेस्टिनेशन तक पहुंच सकें.

एसडीके टूल का इस्तेमाल करने के लिए, आपको एक सेवा बनानी होगी और उसे Android के लिए नेविगेशन एसडीके टूल के साथ रजिस्टर करना होगा. इससे, नेविगेशन के दौरान रीयल टाइम में (लगभग एक सेकंड में) नई नेविगेशन जानकारी मिल सकती है.

इस दस्तावेज़ में, नेविगेशन सेवा बनाने और उसे रजिस्टर करने का तरीका बताया गया है. यह सेवा, SDK टूल से नेविगेशन की जानकारी पाती है और नेविगेशन की स्थिति को डिवाइस को भेजती है.

खास जानकारी

इस सेक्शन में, अपने प्रोजेक्ट में TurnByTurn लाइब्रेरी जोड़ने का तरीका बताया गया है. साथ ही, इसमें बारी-बारी से निर्देश देने की सुविधा बनाने के लिए, हाई-लेवल फ़्लो की खास जानकारी दी गई है.

Maven का इस्तेमाल करके, अपने प्रोजेक्ट में TurnByTurn लाइब्रेरी जोड़ना (सुझाया गया)

TurnByTurn लाइब्रेरी के स्टैंडअलोन वर्शन का इस्तेमाल करने के लिए, यह तरीका अपनाएं:

1. होस्ट की Maven रिपॉज़िटरी को ऐक्सेस करने के लिए, अपना एनवायरमेंट सेट अप करें:

   Maven

   अपनी pom.xml फ़ाइल में ये चीज़ें जोड़ें:

       <project>
         ...
         <repositories>
           <repository>
             <id>google-maven-repository</id>
             <url>https://maven.google.com</url>
           </repository>
         </repositories>
         ...
       </project>
       
       

   ग्रेडल

   अपनी build.gradle फ़ाइल में ये चीज़ें जोड़ें:

   repositories {
       ...
       google()
   }
       

2. अपने Maven या Gradle कॉन्फ़िगरेशन में यह डिपेंडेंसी जोड़ें:

   Maven

   <dependencies>
     ...
     <dependency>
       <groupId>com.google.android.maps</groupId>
       <artifactId>google_turnbyturn</artifactId>
       <version>1.0.0</version>
     </dependency>
   </dependencies>
       
       

   ग्रेडल

   dependencies {
     ...
     implementation 'com.google.android.maps:google_turnbyturn:1.0.0'
   }
       

डाउनलोड की गई JAR फ़ाइल का इस्तेमाल करके, अपने प्रोजेक्ट में TurnByTurn लाइब्रेरी जोड़ना (विकल्प)

TurnByTurn लाइब्रेरी, इस SDK फ़ोल्डर में JAR फ़ाइल के तौर पर उपलब्ध है. अगर आपके पास ऐक्सेस नहीं है, तो अपने प्रतिनिधि से संपर्क करें.

1. google_turnbyturn_*.jar डाउनलोड करें और अनज़िप करें.
2. डाउनलोड की गई JAR फ़ाइल को अपने प्रोजेक्ट की app/libs डायरेक्ट्री में कॉपी करें.

3. अपने बिल्ड में JAR शामिल करने के लिए, build.gradle में ये चीज़ें जोड़ें.

   dependencies {
       ...
       api fileTree(include: ['*.jar'], dir: 'libs')
   }
   

TurnByTurn लाइब्रेरी का इस्तेमाल करना

यहां मोड़-दर-मोड़ निर्देश पाने की सुविधा चालू करने का तरीका बताया गया है. यहां दिए गए सेक्शन में, हर चरण के बारे में जानकारी दी गई है.

1. नेविगेशन से जुड़े अपडेट पाने के लिए सेवा बनाएं.

2. सेवा रजिस्टर करें.

3. नेविगेशन के स्टेटस को समझना.

नेविगेशन से जुड़े अपडेट पाने के लिए सेवा बनाना

नेविगेशन SDK टूल, आपकी TurnByTurn सेवा से जुड़ता है और Android Messenger के ज़रिए नेविगेशन से जुड़े अपडेट भेजता है. इन अपडेट के लिए, नई नेविगेशन सेवा बनाई जा सकती है या किसी मौजूदा सेवा का इस्तेमाल किया जा सकता है.

नेविगेशन से जुड़े अपडेट पाने के लिए किसी सेवा का इस्तेमाल करने का फ़ायदा यह है कि वह सेवा, बैकग्राउंड में अलग प्रोसेस के तौर पर काम कर सकती है.

नीचे दिए गए उदाहरण में, सेवा को नेविगेशन की जानकारी मिलती है. साथ ही, डेटा को NavInfo ऑब्जेक्ट में बदलने के लिए, TurnByTurnManager का इस्तेमाल किया जाता है. इस ऑब्जेक्ट में नेविगेशन की जानकारी होती है.

/**
 *   Receives turn-by-turn navigation information forwarded from NavSDK.
 */
public class NavInfoReceivingService extends Service {
  /** The messenger used by the service to receive nav step updates. */
  private Messenger incomingMessenger;
  private TurnByTurnManager turnByTurnManager;

  private final class IncomingNavStepHandler extends Handler {
    public IncomingNavStepHandler(Looper looper) {
      super(looper);
    }

    @Override
    public void handleMessage(Message msg) {
      // Identify the message through the msg.what field.
      if (TurnByTurnManager.MSG_NAV_INFO == msg.what) {
        // Extract the NavInfo object using the TurnByTurnManager.
        NavInfo navInfo = turnByTurnManager
          .readNavInfoFromBundle(msg.getData()));
      // Do something with the NavInfo
    }
  }
}

@Nullable
@Override
public IBinder onBind(Intent intent) {
  return incomingMessenger.getBinder();
}

@Override
public void onCreate() {
  turnByTurnManager = TurnByTurnManager.createInstance();
  HandlerThread thread =
    new HandlerThread("NavInfoReceivingService",
      Process.THREAD_PRIORITY_DEFAULT);
  thread.start();
  incomingMessenger = new Messenger(
    new IncomingNavStepHandler(thread.getLooper()));
}

मैसेज कोड

NavInfo मैसेज की पहचान, Message क्लास के Message.what फ़ील्ड से की जा सकती है. यह फ़ील्ड, TurnByTurnManager.MSG_NAV_INFO की वैल्यू पर सेट होता है.

नेविगेशन अपडेट के लिए सेवा को रजिस्टर करना

यहां दिए गए कोड स्निपेट, नेविगेशन सेवा को रजिस्टर करते हैं.

boolean isNavInfoReceivingServiceRegistered =
          navigator.registerServiceForNavUpdates(
              getPackageName(), NavInfoReceivingService.class.getName(), numNextStepsToPreview);

सेवा शुरू और बंद करना

नेविगेशन सेवा तब तक चालू रहती है, जब तक Navigation SDK टूल उससे कनेक्ट रहता है. नेविगेशन सेवा के लाइफ़ साइकल को कंट्रोल करने के लिए, startService() और stopService() को मैन्युअल तरीके से कॉल किया जा सकता है. हालांकि, नेविगेशन SDK के साथ अपनी सेवा को रजिस्टर करने पर, आपकी सेवा अपने-आप शुरू हो जाती है और उसे अनरजिस्टर करने पर ही बंद होती है. अपने ऐप्लिकेशन को सेट अप करने के तरीके के आधार पर, हो सकता है कि आप फ़ोरग्राउंड सेवा शुरू करना चाहें. इस बारे में Android दस्तावेज़ में सेवाओं की खास जानकारी में बताया गया है.

सेवा को अनरजिस्टर करना

नेविगेशन से जुड़े अपडेट पाने की सुविधा बंद करने के लिए, नेविगेशन SDK टूल से सेवा को अनरजिस्टर करें.

navigator.unregisterServiceForNavUpdates();

नेविगेशन स्टेटस को समझना

नेविगेशन की मौजूदा स्थिति जानने के लिए, NavInfo.getNavState() का इस्तेमाल करें. यह स्थिति इनमें से कोई एक होती है:

• रास्ते पर है - ENROUTE स्थिति का मतलब है कि गाइडेड नेविगेशन फ़िलहाल चालू है और उपयोगकर्ता दिए गए रास्ते पर है. मौजूदा और अगले मैन्युवर के चरण के बारे में जानकारी उपलब्ध है.

• रास्ता बदला जा रहा है - REROUTING का मतलब है कि नेविगेशन जारी है, लेकिन नेविगेटर नया रास्ता खोज रहा है. आगे की कार्रवाई का चरण उपलब्ध नहीं है, क्योंकि अभी तक कोई नया रास्ता नहीं चुना गया है. सैंपल ऐप्लिकेशन में, नेविगेशन की जानकारी वाले डिसप्ले में "रास्ता बदला जा रहा है..." मैसेज दिखता है. रास्ता मिलने के बाद, NavInfo मैसेज भेजा जाता है. इसमें ENROUTE स्थिति होती है.

• बंद है - STOPPED का मतलब है कि नेविगेशन खत्म हो गया है. उदाहरण के लिए, जब उपयोगकर्ता ऐप्लिकेशन में नेविगेशन से बाहर निकलता है, तो नेविगेशन बंद हो जाता है. सैंपल ऐप्लिकेशन में, STOPPED स्थिति नेविगेशन की जानकारी वाले डिसप्ले को हटा देती है, ताकि चरणों के निर्देशों को दिखाने से रोका जा सके.

फ़ीड डिसप्ले को पॉप्युलेट करना

अब आपने निर्देशों के साथ चलने की सुविधा सेट अप कर ली है. इस सेक्शन में, ऐसे विज़ुअल और टेक्स्ट एलिमेंट के बारे में बताया गया है जिनका इस्तेमाल करके, निर्देशों के साथ चलने वाले फ़ीड के लिए, दिशा-निर्देश वाले कार्ड में जानकारी भरी जा सकती है.

नेविगेशन कार्ड की जानकारी वाले फ़ील्ड

जब उपयोगकर्ता, निर्देशों के साथ नेविगेशन की सुविधा का इस्तेमाल करता है, तो सबसे ऊपर एक नेविगेशन कार्ड दिखता है. इसमें नेविगेशन का डेटा होता है, जो नेविगेशन SDK टूल से भरा जाता है. मिलती-जुलती इमेज में, इन ज़रूरी नेविगेशन एलिमेंट का उदाहरण दिखाया गया है.

इस टेबल में, नेविगेशन की जानकारी वाले फ़ील्ड और उन्हें ढूंढने का तरीका बताया गया है.

नेविगेशन के हर चरण के लिए फ़ील्ड	पूरी यात्रा के लिए फ़ील्ड
StepInfo में मिला	NavInfo में मिला
सड़क का पूरा नाम	बाकी समय
मैन्युवर आइकॉन	डेस्टिनेशन की दूरी
अगले चरण की दूरी
लेन गाइड फ़ील्ड

लेन गाइड

नेविगेशन SDK टूल, नेविगेशन टर्न कार्ड में लेन को लेन और LaneDirection डेटा ऑब्जेक्ट के तौर पर दिखाता है. नेविगेशन के दौरान, Lane ऑब्जेक्ट किसी खास लेन को दिखाता है. साथ ही, इसमें LaneDirection ऑब्जेक्ट की सूची होती है. इस सूची में, इस लेन से किए जा सकने वाले सभी मोड़ों के बारे में जानकारी होती है.

किसी लेन में उपयोगकर्ता को किस दिशा में जाना चाहिए, यह बताने के लिए isRecommended फ़ील्ड का इस्तेमाल किया जाता है.

लेन गाइड के उदाहरण

नीचे दिए गए स्निपेट में, ऊपर दिखाई गई लेन का डेटा दिखाया गया है.

// Lane 1
LaneDirections = [{/*laneShape=*/ STRAIGHT, /*isRecommended=*/ false},
                  {/*laneShape=*/ SLIGHT_LEFT, /*isRecommended=*/ true}]

// Lane 2
LaneDirections = [{/*laneShape=*/ STRAIGHT, /*isRecommended=*/ false}]

मैन्युवर के लिए आइकॉन बनाना

Maneuver सूची, नेविगेट करते समय होने वाले हर संभावित बदलाव के बारे में बताती है. साथ ही, StepInfo.getManeuver() तरीके से किसी चरण के लिए बदलाव की जानकारी मिल सकती है.

आपको मैन्युवर के आइकॉन बनाने होंगे और उन्हें मैन्युवर से जोड़ना होगा. कुछ मैन्युवर के लिए, किसी आइकॉन के साथ एक-एक मैपिंग सेट अप की जा सकती है. जैसे, DESTINATION_LEFT और DESTINATION_RIGHT. हालांकि, कुछ मैन्युवर एक जैसे होते हैं. इसलिए, हो सकता है कि आप एक से ज़्यादा मैन्युवर को एक आइकॉन पर मैप करना चाहें. उदाहरण के लिए, TURN_LEFT और ON_RAMP_LEFT, दोनों को बाईं ओर मुड़ने के आइकॉन पर मैप किया जा सकता है.

कुछ मैन्युवर में एक अतिरिक्त clockwise या counterclockwise लेबल होता है. इसे एसडीके टूल, देश में ड्राइविंग की साइड के आधार पर तय करता है. उदाहरण के लिए, जिन देशों में सड़क की बाईं ओर गाड़ी चलाई जाती है वहां ड्राइवर, राउंडअबाउट या यू-टर्न घड़ी की सुई के घूमने की दिशा में लेते हैं. वहीं, जिन देशों में सड़क की दाईं ओर गाड़ी चलाई जाती है वहां ड्राइवर, राउंडअबाउट या यू-टर्न घड़ी की सुई के घूमने की दिशा में लेते हैं. नेविगेशन SDK टूल यह पता लगाता है कि कोई कार्रवाई बाईं या दाईं ओर के ट्रैफ़िक में की जा रही है या नहीं. साथ ही, सही कार्रवाई का सुझाव देता है. इसलिए, घड़ी की सुई के घूमने की दिशा के हिसाब से, आपके वाहन के मूवमेंट का आइकॉन अलग-अलग हो सकता है.

जनरेट किए गए आइकॉन का इस्तेमाल करना

Android Auto के इस्तेमाल के उदाहरणों को आसान बनाने के लिए, नेविगेशन SDK टूल, कार के मोड़ और लेन के दिशा-निर्देश देने वाले आइकॉन जनरेट करने की सुविधा देता है. ये आइकॉन, Android Auto ऐप्लिकेशन की लाइब्रेरी में दिए गए, इमेज के साइज़ से जुड़े दिशा-निर्देशों के मुताबिक हैं. इनमें 500 x 74 डीपी के बाउंडिंग बॉक्स को टारगेट करने का सुझाव दिया गया है. ज़्यादा जानकारी के लिए, Android के रेफ़रंस दस्तावेज़ में setsLaneImage और CarIcon देखें.

आइकॉन जनरेट करने का उदाहरण

NavigationUpdatesOptions options =
  NavigationUpdatesOptions.builder()
             .setNumNextStepsToPreview(numNextStepsToPreview)
             .setGeneratedStepImagesType(GeneratedStepImagesType.BITMAP)
             .setDisplayMetrics(getResources().getDisplayMetrics())
             .build();
boolean isRegistered =
          navigator.registerServiceForNavUpdates(
              getPackageName(),
              NavInfoReceivingService.class.getName(),
              options);

आइकॉन जनरेशन की सुविधा चालू करने के बाद, TurnbyTurn StepInfo ऑब्जेक्ट, आइकॉन के साथ maneuverBitmap और lanesBitmap फ़ील्ड को पॉप्युलेट करता है.

आगे क्या करना है

• Android Auto ऐप्लिकेशन के लिए:
  • मैप ड्रॉ करें और नेविगेशन चालू करें.