title: When to use application ID or package name a.k.a. is the PackageManager#getLaunchIntentForPackage method name incorrect?
body: <h1>When do I use 'application ID' or 'package'?</h1>
  <p>(or is it 'package name'?)</p>
  <h1>My confusion in a practical situation:</h1>
  <p>One way to switch from one app to another is to get a launch intent for the app, which could be done using (given some <code>context</code>):</p>
  <pre><code>PackageManager manager = context.getPackageManager();
  Intent intent = manager.getLaunchIntentForPackage(packageName);
  </code></pre>
  <p>Note that the parameter's name is called <code>packageName</code> and that even the method name mentions 'package'. However, this is <em>not</em> the package name! It is the application ID we should be using here!</p>
  <p>For example, if I have a debug build type that instead of the release application ID <code>com.example</code> has a debug suffix, e.g. it is <code>com.example.debug</code>, I have to use <code>&quot;com.example.debug&quot;</code> as the parameter to <code>getLaunchIntentForPackage</code>. But the app's package namespace remains unchanged (<a href="https://developer.android.com/studio/build/manifest-merge.html" rel="nofollow noreferrer">by default</a>): it is still <code>com.example</code>! If I don't have my non-debug app installed, the <code>getLaunchIntentForPackage</code> method returns <code>null</code>, because application ID <code>com.example</code> isn't installed.</p>
  <p>So what am I looking at here? I would think that <code>com.example</code> is my package name and that <code>com.example.debug</code> is my application ID. But why does the <a href="https://developer.android.com/reference/android/content/pm/PackageManager.html#getLaunchIntentForPackage(java.lang.String)" rel="nofollow noreferrer">PackageManager#getLaunchIntentForPackage</a> method mention 'package' and 'package name', while would think that it should mention 'application ID' instead?</p>
  <p>Is this just an incorrectly named method in the Android SDK, or am I misunderstanding something?</p>
  <p>I base my question on the following information.</p>
  <h1>From the documentation on <a href="https://developer.android.com/studio/build/application-id" rel="nofollow noreferrer">application IDs</a>, I quote:</h1>
  <blockquote>
  <p>Every Android app has a unique application ID that looks like a Java package name, such as <em>com.example.myapp</em>. This ID uniquely identifies your app on the device and in Google Play Store. If you want to upload a new version of your app, the application ID (and the <a href="https://developer.android.com/studio/publish/app-signing.html" rel="nofollow noreferrer">certificate you sign it with</a>) must be the same as the original APK—if you change the application ID, Google Play Store treats the APK as a completely different app. So once you publish your app, <strong>you should never change the application ID</strong>.</p>
  <p>[...]</p>
  <p>When you create a new project in Android Studio, the <code>applicationId</code> exactly matches the Java-style package name you chose during setup. However, the application ID and package name are independent of each other beyond this point. You can change your code's package name (your code namespace) and it will not affect the application ID, and vice versa (though, again, you should not change your application ID once you publish your app). However, changing the package name has other consequences you should be aware of, so see the section about <a href="https://developer.android.com/studio/build/application-id#change_the_package_name" rel="nofollow noreferrer">modifying the package name</a>.</p>
  </blockquote>
  <p>So the application ID uniquely identifies you app on the Play Store. The package name is the namespace of subpackages and classes in your application code base. So far so good, I understand this.</p>
  <p>However, at the end of this documentation page we have the following even more confusing highlight:</p>
  <blockquote>
  <p><strong>One more thing to know:</strong> Although you may have a different name for the manifest <code>package</code> and the Gradle <code>applicationId</code>, the build tools copy the application ID into your APK's final manifest file at the end of the build. So if you inspect your <code>AndroidManifest.xml</code> file after a build, don't be surprised that the <code>package</code> attribute has changed. The <code>package</code> attribute is where Google Play Store and the Android platform actually look to identify your app; so once the build has made use of the original value (to namespace the <code>R</code> class and resolve manifest class names), it discards that value and replaces it with the application ID.</p>
  </blockquote>
  <p>So here we have multiple contradictions on one page!</p>
  <ol>
  <li>Google Play identifies app by application ID vs. package.</li>
  <li>The manifest's package name can differ from the application ID vs. at compile time the package is overwritten by the application ID by the build tools.</li>
  </ol>
  <p>From this highlight, at least the statement about the build tools overwriting the package name by the application seems to be incorrect, because:</p>
  <p>When creating an intent for activity <code>com.example.MainActivity</code> in app <code>com.example.debug</code> I have to specify <code>com.example.debug</code> as the application ID and <code>com.example.MainActivity</code> as the component name. At runtime, the component name hasn't changed its package name to the application ID, so it seems that the package namespace isn't changed by the build tools?</p>
  <h1>I hope that...</h1>
  <p>...somebody can create a nice answer with various examples that show when an application ID and package (name) are the same, or when they are not, and where the Android system and Google Play actually use which. Please also consider an example with a library dependency: as far as I understand, the library's package namespace doesn't change, but it runs with your application ID, am I right?</p>